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Abstract 

CONTAM  is  a general  purpose,  multi-zone  (nodal)  airflow  and  contaminant  transport  analysis 
tool  that  can  be  used  to  determine  inter-zone  pressure  differences,  airflow  rates  and  contaminant 
transport  in  complex  building  structures.  This  tool  was  developed  by  the  Building  and  Fire 
Research  Laboratory  of  the  National  Institute  of  Standards  and  Technology  (NIST)  for  the 
analysis  of  building  ventilation  systems  and  has  evolved  and  adapted  to  accommodate  a wide 
range  of  building  engineering  disciplines  from  indoor  air  quality  analysis  to  smoke  management 
system  design.  This  report  serves  two  purposes:  as  a supplement  to  the  CONTAMW  2.0  User 
Manual  with  explanations  of  the  most  recent  enhancements  to  the  program  and  to  document  the 
program.  The  documentation  addresses  both  the  graphical  user  interface  (referred  to  herein  as 
ContamW)  and  the  numerical  solver  (referred  to  herein  as  ContamX)  of  version  2.1  of  the 
program,  collectively  referred  to  as  CONTAM. 


Key  Words:  airflow  analysis;  atmospheric  contaminant  transport;  building  technology; 
computer  program;  contaminant  analysis;  design  tool;  indoor  air  quality;  multizone  analysis 


Software  Disclaimer 

This  software  was  developed  at  the  National  Institute  of  Standards  and  Technology  by 
employees  of  the  Federal  Government  in  the  course  of  their  official  duties.  Pursuant  to  title  17 
Section  105  of  the  United  States  Code  this  software  is  not  subject  to  copyright  protection  and  is 
in  the  public  domain.  CONTAM  is  an  experimental  system.  NIST  assumes  no  responsibility 
whatsoever  for  its  use  by  other  parties,  and  makes  no  guarantees,  expressed  or  implied,  about  its 
quality,  reliability,  or  any  other  characteristic.  We  would  appreciate  acknowledgement  if  the 
software  is  used. 

This  software  can  be  redistributed  and/or  modified  freely  provided  that  any  derivative  works 
bear  some  notice  that  they  are  derived  from  it,  and  any  modified  versions  bear  some  notice  that 
they  have  been  modified. 

Certain  trade  names  or  company  products  are  mentioned  in  the  text  to  specify  adequately  the 
experimental  procedure  and  equipment  used.  In  no  case  does  such  identification  imply 
recommendation  or  endorsement  by  the  National  Institute  of  Standards  and  Technology,  nor 
does  it  imply  that  the  equipment  is  the  best  available  for  the  purpose. 

Navigating  This  Document 

This  document  is  made  up  of  three  separate  parts:  Part  1 is  relevant  to  the  typical  users  of  the 
program  and  Parts  2 and  3 are  provided  for  those  interested  in  understanding  the  inner-workings 
of  the  solver  and  graphical  user  interface  (GUI)  respectively.  Part  2 also  contains  information 
related  to  input  and  output  file  formats  that  may  prove  useful  to  the  more  advanced  users  of  the 
program.  If  you  are  viewing  this  document  within  a pdf-viewer  then  you  can  use  the  Bookmarks 
to  navigate  to  various  sections  of  the  document.  You  can  also  use  hyperlinks  that  appear 
throughout  the  document  that  have  been  defined  to  provide  easy  access  to  detailed  information, 
e.g.  function  definitions  in  the  ContamX  program  structure.  After  executing  a link  you  may 
return  to  the  spot  where  the  link  was  called  by  clicking  on  the  left  arrow  in  the  toolbar  above  the 
document,  e.g.,  “Go  to  previous  view’'  button  in  the  Adobe  Acrobat  Reader  as  illustrated  below. 
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Part  1 - Introduction 


PART  1 - CONTAM  2.1  Supplemental  User  Manual 

1.1  Introduction 

This  part  of  the  document  serves  as  a user  manual  for  the  enhancements  embodied  in  CONTAM 
2.1.  It  is  to  be  used  as  a supplement  to  the  CONTAM W 2.0  User  Manual  [2].  This  supplemental 
information  is  also  incorporated  into  ContamW’s  online  help  system 

CONTAM  2.1  includes  the  implementation  of  the  following  enhancements: 

• Wind  pressure  and  contaminant  fields  - The  ability  to  incorporate  data  from  exterior  airflow 
and  pollutant  transport  models,  e.g.,  plume  and  puff  dispersion  models,  to  utilize  detailed 
ambient  wind  pressure  and  contaminant  data  fields  to  provide  boundary  conditions  on  the 
airflow  paths  of  the  envelope  of  built  structures 

• Control  elements  - New  control  elements  to  simulate  time  delays  associated  with  spin- 
up/down  of  fans  and  the  opening/closing  of  dampers  and  to  perform  integration,  peak 
determination  of  sensor  output  over  time,  maximum,  minimum  and  exponential  operations 

• Particle  analysis  - Modified  contaminant  properties  to  simplify  the  analysis  of  airborne 
particles 

• Mass  release  calculation  - The  calculation  of  total  mass  released  by  contaminant  sources 
during  a simulation 

1.2  Working  with  WPC  Files 

A new  method  to  account  for  the  variation  of  external  wind  pressures  and  outdoor  contaminant 
concentrations  over  the  building  envelope  has  been  implemented  in  CONTAM.  This  method 
addresses  the  need  to  allow  for  the  use  of  general,  spatially  varying  wind  pressure  and  ambient 
contaminant  concentrations  such  as  those  from  wind  tunnel  experiments  or  atmospheric  models, 
e.g.,  plume  or  puff  dispersion  simulation  tools.  This  method  involves  the  implementation  of  a 
Wind  Pressure  and  Contaminants  file  (WPC  file).  This  file  provides  exterior  pressure  and/or 
contaminant  concentrations  time  histories  for  every  flow  path  that  connects  to  the  ambient  zone 
including  duct  terminals  and  outdoor  air  intakes  of  CONTAM's  simple  air  handling  systems. 

The  WPC  files  are  created  externally  to  CONTAM,  however  their  creation  can  be  assisted  by 
ContamW  that  creates  a Path  Location  Data  (PLD)  file  listing  all  the  airflow  path  locations  that 
are  connected  to  the  ambient  zone.  The  following  figure  illustrates  the  interaction  between 
CONTAM  and  the  WPC  file.  The  dashed  lines  in  the  figure  represent  optional  components.  The 
WPC  file  is  an  ASCII  file  that  could  be  created  using  conventional  means,  e.g.,  spreadsheet 
converted  to  text.  Once  could  also  develop  a WPC  File  Converter  program  to  create  the  files 
from  External  Wind  Pressure  and  Contaminant  data  files  created  by  a separate  tool,  e.g.,  exterior 
CFD  program.  A converter  could  then  work  with  the  PLD  file  to  create  a WPC  file  specific  to 
the  building  in  question,  i.e.,  the  PRJ  file.  ContamW  provides  a means  to  activate  a user- 
selectable  converter.  The  details  of  the  WPC  and  PLD  file  formats  are  presented  in  the  sections 
titled  Wind  Pressure  and  Contaminant  File  (.WPC),  and  Path  Location  Data  File  (.PLD) 
respectively  of  Part  2 of  this  document.  CONTAM  does  not  include  either  an  EWC  file  creation 
tool  or  an  EWC-to-WPC  converter  tool. 
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WPC  File  Implementation  Schematic 


Steps  to  implement  WPC  files: 

• Specify  WPC  file  usage  parameters  (Weather^Use  WPC  File...) 

o Select  type  of  data  the  WPC  file  includes  - wind  pressures  and/or  contaminants 
o Select  existing  WPC  file 
Or 

o Select  EWC  File  Converter  program  (optional  and  user-provided) 

Specify  converter  parameters:  equivalent  origin,  location  tolerance,  date  and  time  info 
Select  EWC  input  file  to  EWC  File  Converter  program 
Specify  name  of  WPC  file  to  create 

• Enter  Coordinate  Information  for  each  external  flow  path 
o Airflow  paths 

o Duct  terminals 

o Outdoor  air  intakes  of  simple  air  handling  systems 

• Run  Simulation  or  Create  ContamX  Input  File  for  batch  processing.  Either  option  will 
activate  the  WPC  file  implementation  routines  (as  needed)  that  will  create  a PLD  file,  call  the 
converter  program,  compare  WPC  and  PLD  files  and  notify  user  of  discrepancies  between 
them. 

1.2.1  WPC  Usage  Parameters 

The  following  parameters  are  required  to  specify  the  usage  of  a WPC  file  when  performing  a 
simulation.  Access  these  parameters  via  the  Weather— »WPC  File...  menu  item.  The  values  in 
the  group  labeled  WPC  File  are  required,  while  the  others  are  only  necessary  if  implementing  an 
EWC  File  Converter  program. 

j WPC  File 

Use  this  group  of  data  to  specify  the  .WPC  file  to  use  when  performing  a simulation  and  the  type 
of  data  contained  within  the  file.  NOTE:  Check  at  least  one  of  the  two  check  boxes  in  order  to 
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activate  the  Coordinate  Information  parameters  on  the  Airflow  Path,  Duct  Terminal,  and  Simple 
Air  Handling  System  property  sheets. 

Wind  Pressures:  Check  this  box  to  use  wind  pressures  from  a WPC  File. 

Contaminant  Concentrations:  Check  this  box  to  use  contaminant  concentrations  from  a 
WPC  File.  This  box  will  only  be  activated  if  you  have  already  defined  contaminants  within 
the  current  project. 

Name:  This  is  the  name  of  the  WPC  File  to  use  during  the  simulation.  You  can  either  use  the 
Browse...  button  to  select  an  existing  file,  or  enter  the  name  you  would  like  the  EWC  File 
Converter  to  give  to  a new  file. 

Description:  This  will  display  the  description  line  of  the  WPC  File  if  it  exists,  or  you  can 
enter  a description  for  a new  WPC  File. 

□ External  Wind  and  Contaminant  Data 

The  External  Wind  Pressure  and  Contaminant  file  contains  the  external  contaminant 
concentrations  and  pressures  that  the  EWC  File  Converter  (which  must  be  developed  for  your 
specific  application)  will  convert  into  a WPC  File. 

File  Name:  Use  the  Browse...  button  to  select  an  existing  EWC  File. 

Program  to  Create  WPC  File:  Use  the  Browse...  button  to  select  the  EWC  File  Converter 
program  to  use. 

□ Coordinate  Transformation  Data 

These  parameters  can  be  used  by  an  EWC  File  Converter  to  establish  the  relationship 
between  the  coordinates  of  the  External  Wind  Pressure  and  Contaminant  file  and  the 
CONTAM  project  file.  No  transformation  is  required  if  the  coordinate  systems  for  the  PRJ 
and  EWC  tiles  are  consistent.  These  values  are  stored  in  the  PLD  file  by  ContamW. 

Origin  (X,  Y and  Z):  The  location  of  the  origin  of  the  CONTAM  PRJ  file  with  respect  to  the 
origin  of  the  External  Wind  Pressure  and  Contaminant  file. 

Rotation  Data:  The  rotation  of  the  x and  y axes  of  the  EWC  coordinate  system  about  the  z 
axis  to  align  with  the  x and  y axes  of  the  CONTAM  coordinate  system.  Counter-clockwise  is 
considered  the  positive  direction. 

□ Conversion  Tolerance 

These  are  the  tolerances  that  an  EWC  File  Converter  might  use  to  determine  how  closely 
information  in  the  EWC  File  and  the  PLD  File  must  match  in  order  to  resolve  contaminant 
(species)  and  location  data.  These  values  are  stored  in  the  PLD  file  by  ContamW. 

Species:  Species  can  be  resolved  by  their  molecular  weight,  i.e.,  the  molecular  weight  of 
each  species  defined  in  ContamW  and  the  WPC  file  must  not  differ  by  more  than  this  amount 
to  be  considered  the  same  species. 

Location:  Locations  can  be  resolved  by  their  distance  as  determined  by  an  EWC  File 
Converter . e.g.,  distance  to  center  of  a grid  cell.  Units  within  the  PLD  File  are  in  meters. 
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□ Date  and  Time 

These  parameters  can  be  used  by  an  EWC  File  Converter  to  determine  the  date  and  time 
values  written  to  the  WPC  File  for  the  convenience  of  working  according  to  CONTAM's 
schedules.  These  values  are  stored  in  the  PLD  file  by  ContamW. 

Data  Time  Shift:  The  format  for  this  value  is  hh:mm:ss.  An  EWC  File  Converter  could  add 
this  value  to  the  EWC  File  time.  For  example  an  EWC  File  Converter  could  create  a file  that 
begins  at  00:00:00  and  set  the  next  time  to  be  the  Data  Time  Shift  you  enter  here.  The  data 
for  these  two  times  would  be  the  initial  values  in  the  EWC  File. 

Start  and  End  Date:  The  format  for  this  value  is  mmmdd.  For  example,  enter  January  1 as 
JanOl.  An  EWC  File  Converter  could  use  this  to  output  the  date(s)  to  use  when  running 
transient  simulations. 

1.2.2  Envelope  Opening  Locations 

When  using  WPC  Files  you  must  enter  the  coordinates  for  each  opening  connected  to  the 
ambient.  CONTAMW  now  provides  a means  to  do  this  for  Airflow  Paths , Duct  Terminals , and 
Outdoor  Air  Intakes  of  Simple  Air  Handling  Systems.  This  information  is  provided  on  the  Wind 
Pressure  Property  Pages  of  the  Airflow  Path  Properties  and  Duct  Junction  Properties  and  on  the 
AHS  Property  Page  of  the  Simple  Air  Handling  System  Properties  input  dialog  boxes.  The 
location  information  will  be  used  to  create  the  PLD  File  which  in  turn  is  used  to  verify  there  is 
matching  information  within  the  WPC  File  prior  to  performing  simulations  using  the  WPC  File. 

Even  though  every  opening  requires  location  data  when  simulating  with  WPC  Files , they  do  not 
necessarily  have  to  be  unique.  They  simply  must  match  a location  within  the  WPC  File. 

NOTE:  Either  the  Wind  Pressures  or  Contaminant  Concentrations  check  boxes  on  the  Wind 
Pressure  and  Contaminants  (WPC)  File  Parameters  dialog  box  must  be  checked  in  order  to 
access  the  coordinate  input  fields  of  these  property  pages. 

1.2.2. 1 Airflow  Paths  and  Duct  Terminals 

Enter  the  X and  Y coordinates  and  units  for  the  selected  airflow  path  or  duct  terminal.  The  Z 
coordinate  will  be  calculated  by  ContamW  to  be  the  Relative  Elevation  of  the  airflow  path  or 
duct  terminal  plus  the  Elevation  of  the  building  level  on  which  the  path  or  terminal  is  located. 

1.2.2. 2 Outdoor  Air  Intakes  of  Simple  Air  Handling  Systems 

Enter  the  X,  Y and  Z coordinates  and  units  for  the  outdoor  air  intake  of  the  selected  Simple  AHS. 
Enter  the  Z coordinate  as  the  height  of  the  midpoint  of  the  outdoor  air  intake  with  respect  to  the 
building  reference  height. 

1.2.3  Running  Simulations  using  a WPC  File 

To  run  a simulation  using  a WPC  file,  you  must  have  checked  either  the  Wind  Pressures  or 
Contaminant  Concentrations  check  box  on  the  Wind  Pressure  and  Contaminant  (WPC)  File 
Parameters  dialog  box.  When  you  choose  Run  Simulation  (or  Create  ContamX  Input  File)  from 
the  Simulation  menu,  ContamW  will  perform  a series  of  checks  to  make  sure  that  all  the  path 
locations  have  been  defined  and  match  those  in  the  WPC  file  if  it  exists  and  that  the  species 
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match  between  the  PRJ  and  the  WPC  files.  It  will  call  the  EWC  File  Converter  and  create  a WPC 
file  if  an  EWC  file  converter  has  been  identified. 

ContamW  will  provide  error  messages  as  needed  and  highlight  paths  on  the  SketchPad  to  reveal 
those  for  which  location  data  are  not  defined  or  the  PLD  and  WPC  coordinates  do  not  match 
within  the  specified  tolerance.  If  there  are  errors  with  specific  openings,  you  can  take  this 
opportunity  to  correct  them. 

1.3  Control  Elements 

Several  building  control  elements  have  been  added  to  CONTAM.  These  elements  are  described 
below. 

□ Continuous  Value  File  (CVF) 

This  control  element  allows  you  to  implement  general  schedules  by  obtaining  input  values 
from  a file.  This  allows  you  to  create  schedules  that  are  not  restricted  by  the  12 -day  schedule 
limit  of  CONTAM's  week  schedules.  The  file  is  referred  to  as  a continuous  value  file.  This 
file  is  an  ASCII  file  that  you  create  according  to  the  format  specified  in  the  Continuous  Value 
File  (.CVF)  section  in  Part  2 of  this  document.  You  can  only  use  one  CVF  file  per 
simulation,  and  the  file  may  contain  multiple  lists  of  values.  Value  lists  are  referenced  by 
Value  name  which  are  column  headings  in  the  file. 

Value  Name:  Select  the  name  of  a set  of  values  from  the  list  of  headings  as  they  appear  in 
the  CVF  file. 

File  Name:  This  field  simply  displays  the  CVF  file  that  contains  the  data  that  will  be  used  by 
the  control  node  during  simulation.  You  must  use  the  Data— ^Continuous  Values  File... 
menu  item  to  select  the  file  you  want  to  use  prior  to  creating  CVF  control  nodes. 

Node  Name:  This  is  an  optional  name  you  can  provide  for  this  control  node.  This  name  can 
be  used  to  reference  this  node  with  a Phantom  control  node. 

□ Discrete  Value  File  (DVF) 

This  control  element  allows  you  to  implement  scheduled  discrete  events  by  obtaining  event 
times  and  values  from  a file.  This  allows  you  to  create  schedules  that  do  not  repeat  according 
to  CONTAM's  week  schedules.  The  file  is  referred  to  as  a discrete  value  file.  This  file  is  an 
ASCII  file  that  you  create  according  to  the  format  specified  in  the  Discrete  Value  File  (.DVF) 
section.  You  can  only  use  one  DVF  file  per  simulation,  and  the  file  may  contain  multiple  lists 
of  events.  Event  lists  are  referenced  by  Value  name  which  are  column  headings  in  the  file. 

Value  Name:  Select  the  name  of  a value  from  the  list  of  headings  as  they  appear  in  the  .DVF 
file. 

File  Name:  This  field  simply  displays  the  DVF  file  that  contains  the  data  you  need.  You 
must  use  the  Data-»Discrete  Values  File...  menu  item  to  select  the  file  you  want  to  use 
prior  to  creating  a DVF  control  node. 

Node  Name:  This  is  an  optional  name  you  can  provide  for  this  control  node.  This  name  can 
be  used  to  reference  this  node  with  a Phantom  control  node. 
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□ Scheduled  Delay 

This  control  element  provides  the  ability  to  simulate  time  delays  associated  with  the  ramping 
up/down  of  system  components  changing  between  states,  e.g.,  the  spin  down  of  a fan  or  the 
opening/closing  of  a damper.  The  scheduled  delay  element  allows  you  to  define  a schedule 
according  to  which  the  change  of  state  occurs.  The  output  will  change  according  to  this 
schedule  when  the  input  changes. 

Node  Name:  This  is  an  optional  name  you  can  provide  for  this  control  node.  This  name  can 
be  used  to  reference  this  node  with  a Phantom  control  node. 

Schedule  - Signal  Increasing:  Select/enter  a day  schedule  that  characterizes  the  delay  in  an 
increasing  signal.  The  schedule  must  be  trapezoidal  beginning  with  a value  of  0.0  at  time 
00:00:00  and  increase  to  a value  of  1.0  before  24:00:00.  Only  one  increasing  time  period  per 
schedule  will  be  allowed. 

Schedule  - Signal  Decreasing:  Select/enter  a day  schedule  that  characterizes  the  delay  in  a 
decreasing  signal.  The  schedule  must  be  trapezoidal  beginning  with  a value  of  1.0  at  time 
00:00:00  and  decrease  to  a value  of  0.0  before  24:00:00.  Only  one  decreasing  time  period  per 
schedule  will  be  allowed. 

Description:  Enter  an  optional  description  for  this  control  element. 

□ Exponential  Delay 

This  control  element  provides  the  ability  to  simulate  time  delays  associated  with  the  ramping 
up/down  of  system  components  changing  between  states,  e.g.,  the  spin  down  of  a fan  or  the 
opening/closing  of  a damper.  The  exponential  delay  element  allows  you  to  define  an 
exponential  delay  based  on  a time  constant. 

Node  Name:  This  is  an  optional  name  you  can  provide  for  this  control  node.  This  name  can 
be  used  to  reference  this  node  with  a Phantom  control  node. 

Time  Constants 

Increase:  Enter  the  amount  of  time  it  should  take  for  the  output  signal  to  exponentially 
increase  by  ( 1 - l/e)%  of  the  total  change  in  the  input  signal  when  it  rises  from  one  state  to 
the  next.  The  format  is  hh:mm:ss. 

Decrease:  Enter  the  amount  of  time  it  should  take  for  the  output  signal  to  exponentially 
decrease  by  ( 1 - l/e)%  of  the  total  change  in  the  input  signal  when  it  falls  from  one  state  to 
the  next.  The  format  is  hh:mm:ss. 

Description:  Enter  an  optional  description  for  this  control  element. 

□ Maximum  and  Minimum 

The  output  w ill  be  the  maximum  or  minimum  of  all  input  signals  to  the  control  node  each 
time  step.  Once  a node  is  defined  to  be  of  this  type,  up  to  three  input  signals  can  be  drawn 
directly  into  it.  More  signals  can  be  cascaded  through  the  use  of  phantom  control  elements. 

Node  Name:  This  is  an  optional  name  you  can  provide  for  this  control  node.  This  name  can 
be  used  to  reference  this  node  with  a Phantom  control  node. 

Description:  Enter  an  optional  description  for  this  control  element. 
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□ Integrate  over  time 

The  output  will  be  the  integration  over  time  of  input  signal  1 (horizontal)  controlled  by  input 
signal  2 (vertical).  Integration  occurs  when  input  signal  2 > 0;  there  is  no  integration  when 
input  signal  2 = 0;  the  integral  is  reinitialized  to  zero  when  input  signal  2 < 0.  A simple 
trapezoidal  integration  method  is  used. 


□ 


Running  average 

The  output  will  be  the  average  of  the  input  signal  integrated  over  the  time  span,  Atint,  set  by 
the  user:  out  = | indt  A tmt  . At  the  start  of  simulation,  when  the  simulated  time  is  less 


At,, 


than  the  time  span,  the  output  will  be  the  average  of  the  input  up  to  that  time. 


Node  Name:  This  is  an  optional  name  you  can  provide  for  this  control  node.  This  name  can 
be  used  to  reference  this  node  with  a Phantom  control  node. 


Time  Span:  Enter  the  amount  of  time  included  in  the  running  average,  Atmt-  The  format  is 
hh:mm:ss. 

Description:  Enter  an  optional  description  for  this  control  element. 


1.4  Particulate  Contaminants 

The  properties  of  species/contaminants  have  been  enhanced  to  simplify  the  simulation  of 
particulate  contaminants  with  CONTAM.  Two  properties  have  been  added:  mean  diameter  and 
effective  density’.  Also,  the  units  for  concentration  now  include  particle-related  units.  These  units 
include  # per  unit  mass  of  air  and  # per  unit  volume  of  air.  The  mean  diameter  and  effective 
density  are  currently  only  utilized  to  convert  contaminant  concentrations  between  particle  count 
units  and  mass  and  volumetric  units. 

Mean  Diameter:  Enter  the  mean  particle  diameter  for  particulate  species. 

NOTE:  This  is  not  necessarily  meant  to  be  the  aerodynamic  diameter,  and  that  the  current 
contaminant  source  models  do  not  treat  particles  different  from  gaseous  contaminants. 

Effective  Density:  Enter  a density  that  you  want  CONTAM  to  use  as  the  effective  density  of  a 
species  you  want  to  consider  to  be  a particulate  species. 

1.5  Calculation  of  Total  Mass  Released  from  Sources 

The  total  amount  of  mass  generated/removed  by  each  source  within  a project  is  now  calculated 
and  output  to  the  CONTAMX2.CSM  file  located  in  the  Contain W program  directory.  The 
following  shows  a sample  of  the  data  output.  The  first  two  columns  are  the  source/sink  number 
and  the  zone  number  for  referencing  back  to  ContamW. 


Contaminant 
s/s  # zn  # 

1 1 

2 1 

3 1 


source/ sink 
generated 
6 . 000e-004 
6 . 000e-004 
1 . 000e+000 


summations . 
removed  [kg] 
0 . 000e+000 
0 . 000e+000 
0 . 000e+000 


species 

Cl 

Cl 

C2 
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PART  2 - ContamX  Program  Documentation 

2.1  Introduction 

This  documentation  is  intended  as  an  aid  to  understanding  the  ContamX  2.1  computer  code  and 
is  meant  primarily  to  address  the  logical  structure  of  the  program.  The  numerical  algorithms  are 
explained  in  the  CONTAMW  2.0  User  Manual  [2]. 

The  overall  logical  structure  of  the  program  is  presented  below  in  Section  2.3  Program  Structure 
Overview.  This  material  is  not  necessary  for  the  general  user  of  the  program,  but  is  provided  for 
those  interested  in  understanding  or  perhaps  enhancing  its  capabilities.  You  can  use  the 
hyperlinks  to  jump  to  detailed  descriptions  of  the  highlighted  functions.  After  executing  a link 
you  may  return  to  the  spot  where  the  link  was  called  by  clicking  on  the  left  arrow  in  the  toolbar 
above  the  document.  This  process  is  designed  to  facilitate  both  the  rapid  review  of  program 
structure  and  quick  access  to  the  details  of  the  calculations.  If  working  from  a hard  copy  simply 
keep  in  mind  that  functions  are  presented  alphabetically.  There  are  also  many  small  functions 
performing  simple  operations  that  are  called  from  many  places  in  the  program  - see  Utility 
Functions.  A special  method  is  used  to  store  the  data  for  the  solution  of  the  simultaneous 
equations  - see  Sparse  Matrix  Data  Structure.  That  is  followed  by  a brief  description  of  some  of 
the  numerical  methods  - see  Solution  of  the  Species  Differential  Equations. 

2.2  Development  Environment 

CONTAMX  Version  2.1  was  developed  using  Microsoft  Visual  C++  versions  6.0  and  .NET.  It  is 
basically  a console  application  written  in  the  C programming  language.  However,  the  program 
does  require  Microsoft  Windows  in  order  to  display  simulation  progress  in  a dialog  box.  Other 
than  that,  it  could  be  compiled  in  a non-Windows  environment  with  minor  modifications  to  the 
source  code. 


Part  2 - ContamX  Program  Structure 


2.3  ContamX  Program  Structure 

This  section  presents  the  program  structure  of  the  solver,  ContamX.  Section  2.3.1  presents  the 
overall  program  structure,  2.3.2  presents  the  main  solver  functions  in  alphabetical  order,  2.3.3 
presents  the  utility  functions  used  by  the  solver,  2.3.4  presents  the  sparse  matrix  data  structure 
and  2.3.5  presents  the  solution  to  the  species  differential  equations. 

2.3.1  Overall  Program  Structure 

Program  initialization  [mostly  from  main( ) in  contamx. c] 

Determine  path  to  C0NTAMX2.EXE 
Open  CONTAMX2.LOG  file  for  informative  dumps 
Determine  path  to  project  file  - command  line  or  interactive  input 
Determine  if  dialog  box  used 

if  so,  open  it  and  start  ContamX  thread, 
otherwise,  continue  ContamX  in  DOS  window 
Set  output  mode  (dialog  box  or  DOS  window)  for  error  messages  [from  contamx()j 
Data  initialization  [from  contamx( ) in  contamx. c] 

Read  project  file  - see  prj  read( ) 

Complete  ContamX  data  structures  - see  sim  data( ) 

Create  simulation  arrays  [from  contamx( );  see  mat  initO 
Set  up  airflow  matrices  - see  af  mat  set( ) 

Set  up  non-trace  mass  matrices  - see  mf  mat  set( ) 

Set  up  trace  mass  matrices  - see  mf  mat  sett ) 

Report  equation  numbers  to  LOG  file 
Initialize  simulation  [from  contamx( ) in  contamx. c] 

Set  start/end  dates  and  times 
Open/initialize  weather  file  - see  weather  init{ ) 

Open/initialize  contaminant  file  - see  ambtctm  init( ) 

Initialize  schedules  and  control  values  - see  Ctrl  sim( ) 

Open  simulation  output  files 
Perform  simulation  [from  contamx( ) in  contamx.c] 

Initialize  flow  and  mass  fraction  values 
from  restart  file  - resget 
or  by  steady-state  calculation  - see  sim  lnit{ ) 

Perform  transient  or  cyclic  calculation  - see  sim  loop( ) 

Normal  program  termination  [from  contamx( ) in  contamx.c] 

Report  simulation  performance  to  LOG  file 
De-allocate  all  earlier  heap  allocations  - see  mat  term( ) 

Perform  memory  checks 
Close  LOG  file 

Return  to  main();  return  to  operating  system 
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2.3.2  ContamX  Solver  Functions 

□ af_mat_alc( ) 

[ function  in  file  matset.c] 

Allocate  remaining  airflow  solution  arrays. 

Determine  number  of  non-zero  coefficients  in  symmetric  matrix  - in  ija_minset( ) 

Allocate  and  set  the  ija  index  vector  - in  ija_minset( ) 

Allocate  the  sa,  b,  and  x coefficients  vectors 

For  symmetric  skyline  solution  method  allocate  remaining  arrays  - in  sky_alc( ) 

For  conjugate  gradient  method  allocate  p,  pp,  r,  rr,  z,  zz,  and  preconditioning  vectors 
For  Gauss  elimination  allocate  aa  full  matrix 

□ af_mat_set(  ) 

[function  in  file  matset.c] 

Set  up  airflow  matrices. 

Transfer  control  parameters  from  _rcdat  to  the  structure  for  airflow  calculations 
Set  up  vector  of  pointers  to  nodes  with  constant  pressure  nodes  last 
Determine  positions  of  all  non-zero  elements  in  flow  solution  matrix  - in  acolset( ) 

Allocate  and  fill  the  ijf  vector  sparse  data  mapping  - see  Sparse  Matrix  Data  Structure 
For  the  skyline  method  for  solving  simultaneous  algebraic  equations 
Report  the  initial  matrix  profile  structure  - in  ija_prfl( ) 

Compute  new  sequence  of  equations  to  reduce  average  profile  - in  ija_optord( ) 

Reset  the  airflow  equation  numbers  in  the  node  data  structures 
Report  the  final  matrix  profile  structure 
Allocate  remaining  arrays  depending  on  solution  method  - see  af  mat  alc( ) 

Set  pointers  for  off-diagonal  elements  in  the  link  structures 
Report  solution  notes  to  the  LOG  file 

□ ambtctm  get( ) 

[function  in  file  weather.c] 

Get  the  weather  file  data  for  the  current  simulation  time. 

Note:  the  ambtctm  structure  defined  in  weather.c  holds  data  for  computing  the  contaminant 
mass  fractions  at  the  current  simulation  time  (_sim_time)  from  data  in  the  contaminant  file  at  the 
times  (timeO  and  timel)  that  bound  the  simtime. 

Set  the  contaminant  file  pointer 
Reset  time  at  end-of-day 

Read  the  contaminant  file  until  timeO  < _sim_time  <=  timel 
Reset  timeO  and  corresponding  data  as  necessary 
Check  the  data  date 

Read  and  store  the  time  and  corresponding  contaminant  data 
Determine  the  mass  fraction  of  the  first  non-trace  contaminant 
Set  contaminant  data  for  current  simulation;  use  linear  interpolation  if  not  at  timel 
Transfer  data  to  the  structure  for  _ambt  node  global  variable 
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□ ambtctmjnit( ) 

[ function  in  file  weather,  c] 

Initial  processing  of  the  contaminant  file. 

Open  the  contaminant  file  - using  nxtopen( ) 

Confirm  file  type  and  version 

Read  the  contaminant  file  start  and  end  dates 

Confirm  simulation  dates  within  contaminant  file  dates 

Read  number  of  species  in  file  and  allocate  vectors  in  _ambtctm  structure 

Read  species  names  and  determine  which  match  simulation  contaminants 

Position  contaminant  file  at  the  simulation  start  date 

Read  and  store  contaminant  data  for  time  00:00:00 

For  cyclic  simulation  save  position  in  contaminant  file  of  first  time  step 

Determine  the  mass  fraction  of  the  first  non-trace  contaminant 

The  weather  and  contaminant  files  are  read  using  the  nxtword( ) utility  function.  This  requires 
that  the  _unxt  file  pointer  be  set  to  the  weather  file  or  the  contaminant  file  before  each  is  read. 


□ calc_SP( ) 

[function  in  file  simulate,  c] 

Calculate  stack  pressures  for  each  flow  path. 

This  function  computes  the  Pi,  P2,  and  pg(zi-Z2)  terms  from  the  Bernoulli  equation: 


A P = 


p : + 


pr 


2 x 


pV{ 


2 \ 


+ P§(z  1 


Pi  and  P2  are  computed  by  a hydrostatic  adjustment  to  the  reference  pressures  in  nodes  1 and  2. 
zj  and  Z2  are  the  elevations  of  the  ends  of  the  link  relative  to  nodes  1 and  2.  For  airflow  paths  the 
elevations  are  identical.  They  may  differ  for  ducts.  The  algorithm  includes  hydrostatic 
equations  for  incompressible  and  compressible  air. 

The  final  result  is  an  estimate  for  the  pressure  drop  across  each  opening  based  on  the  reference 
pressures  in  the  connected  nodes,  the  wind  pressure,  and  the  'stack*  pressure. 


□ calc_WP( ) 

[function  in  file  simulate,  c] 

Calculate  wind  pressures  for  each  flow  path. 

The  wind  pressure  for  links  not  connecting  to  the  ambient  node  is  zero.  It  is  also  zero  if  no  wind 
pressure  model  has  been  specified  for  the  link.  Wind  pressure  models  include  constant  value, 
linear  interpolation  using  lint  1 d( ),  spline  interpolation  using  splint( ),  and  a trigonometric 
interpolation  using  htrigf( ),  betw  een  user  specified  wind  pressure  values  as  a function  of  relative 
azimuth  angle. 


□ ctrl_links( ) 

[function  in  file  prjdata.c] 

Set  control  nodes  and  links  for  simulation. 
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Set  pointers  to  incoming  data  according  to  data  type  and  number 
Create  linked  list  of  control  nodes  in  calculation  sequence 

Here  it  is  necessary  to  set  the  pointers  in  sensors  to  the  proper  node  data  (for  zones  and 
junctions)  and  the  proper  link  data  (for  paths  and  ducts).  Note  that  nodes  and  links  can  be  sensed 
and  controlled  making  it  is  impossible  to  place  the  control  data  in  the  project  file  so  that  the 
referenced  items  have  been  defined. 

The  control  structures  are  then  placed  in  a linked  list  (starting  at  CtrlO)  so  that  when  a node  is 
called  while  sequentially  processing  the  list  in  ctrl_sim(  ) the  input  signals  will  be  current.  The 
sequence  was  determined  in  ContamW  in  function  ctrl_order( ) in  file  prjpack.c. 

□ ctrl_sim( ) 

[ function  in  ctrlsim.c ] 

Process  day-schedules,  exposure-schedules , and  controls. 

Set  clock-time  (inch  DST)  and  day  type 
Loop  through  the  week-schedule  list 
Loop  through  the  control  nodes  list 
Set  any  scheduled  zone  temperatures 
Loop  through  the  exposure-schedule  list 

□ de_mat_alc( ) 

[function  in  fde  matset.c] 

Allocate  differential  equation  solution  arrays. 

Determine  number  of  non-zero  coefficients  in  symmetric  matrix  - see  ija  minsetf ) 

Allocate  and  set  the  ija  index  vector  - see  ija  minsetC ) 

Allocate  the  sa,  b,  and  x coefficients  vectors 

For  symmetric  skyline  solution  method  allocate  remaining  arrays  - in  sky_alc( ) in  file  matset.c 
For  conjugate  gradient  method  allocate  p,  pp,  r,  rr,  z,  zz.  and  preconditioning  vectors 
For  Gauss  elimination  allocate  aa  full  matrix. 

□ FillAf() 

[function  in  afesim.c] 

Fill  the  Jacobian  matrix  for  airflows. 

Clear  the  Jacobian  coefficients  vector 
Loop  through  all  air  links 

Initialize  the  coefficients  on  the  diagonal  to  dM/dt  for  variable  pressure  nodes 
Initialize  the  coefficients  on  the  diagonal  to  1.0  for  variable  pressure  nodes 
Initialize  the  X F and  X |F|  values  for  each  node. 

Loop  through  all  air  links 

If  a numerical  derivative  is  being  computed 

Compute  flows  for  adjusted  pressure  drop 
For  each  flow  (1  or  2)  through  the  link 

Compute  dF/dP  if  a numerical  derivative  is  used 
Add  flows  to  the  X F and  X FI  values 
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Add  dF/dP  value  to  the  appropriate  coefficients  in  the  Jacobian  vector 
Check  for  zeroes  on  the  diagonal  (would  cause  divide-by-zero  in  solution) 

Set  any  such  nodes  to  constant  pressure  and  recompute  all  values 


Note  the  use  a linked  list  of  link  (path)  structures  and  of  C pointer  to  functions: 

:or ( pp=_pafpO;  pp;  pp=pp->next)  //  loop  through  all  flow  paths 
{ ~ 

IX  (*pf) (AF_PATH  ) = pp- >pe- >pfunc ; //  pointer  to  simulation  function 

pf ( pp  ) ; //  compute  the  flow(s)  through  path  pp 

I he  linked  list  provides  a very  simple  structure  to  loop  through  the  flow  paths.  The  pointers  to 
functions  provide  a way  to  call  the  different  types  of  flow  paths  without  creating  a switch 
statement  to  access  each  different  type  of  path.  The  functions  to  evaluate  each  different  type  of 
tlow  path  or  duct  are  included  in  file  afesim.c. 

j Fill_Mf(  ) 

[function  in  solvmfc] 

j ija  minset( ) 

[ f unction  in  file  mcitset.c] 

Minimize  the  sparse  matrix  index  vector. 

Reduce  the  "full"  sparse  matrix  index  vector,  ijfi  to  ija  which  does  not  include  diagonal  elements 
or  upper  triangle,  if  symmetric.  Call  once  with  count  = 0 to  determine  size  of  ija , then  call  with 
count  = 1 to  fill  ija. 

j ija_optord( ) 

[function  in  file  matset.c] 

Determine  the  optimum  (minimum  profile)  ordering  for  a set  of  simultaneous  equations. 

From  the  old  sparse  matrix  index  vector  ija  (see  Sparse  Matrix  Data  Structure)  use  the  ACM 
Transactions  On  Mathematical  Software  (TOMS)  582  algorithm  to  compute  a new  optimum 
ordering  for  the  variable  pressure/mass/...  rows.  The  TOMS  582  algorithm  has  been  converted 
from  Fortran  to  C in  file  gpskc.c.  Return  the  new  ordering  in  the  new  vector.  Return  1 if  the 
ordering  has  changed,  0 if  it  has  not. 

j init_Af(  ) 

[function  in  solvaf.c] 

Use  linear  relations  to  determine  initial  guess  for  pressures. 

Zero  the  sparse  matrix  array 

Loop  through  all  links  setting  airflow  matrix  coefficients  for  linear  flow  elements  models 
Solve  the  simultaneous  linear  equations  for  node  pressures  - see  solve  slae( ) 

Set  up  the  coefficients  of  the  airflow  matrix  so  that  solution  of  the  simultaneous  linear  equations 
will  give  an  initial  guess  of  pressures  to  start  the  Newton-Raphson  method  for  solving  the  non- 
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linear  airflow  equations.  This  initialization  tends  to  save  a few  N-R  iterations  and  is  useful  for 
cases  involving  large  numbers  of  airflow  nodes. 

□ init_Mfn( ) 

[function  in  solvmfc] 

Initialize  arrays  for  non-  trace  mass  fraction  calculations. 

Set  the  initial  mass  fractions  in  the  zones  and  junctions. 

Set  the  initial  mass  fractions  in  the  boundary  layer  controlled  sinks. 

Set  up  the  matrix  for  computing  the  mass  fractions  - in  Fill_Mf( ) 

□ init_Mft(  ) 

[ function  in  solvmfc] 

Initialize  arrays  for  trace  mass  fraction  calculations. 

Set  the  initial  mass  fractions  in  the  zones  and  junctions. 

Set  the  initial  mass  fractions  in  the  boundary  layer  controlled  sinks. 

Set  up  the  matrix  for  computing  the  mass  fractions  - in  Fill_Mf( ) 

□ mat_init( ) 

[function  in  file  contamx.  c] 

Allocate  the  matrices  for  solving  airflows  and  mass  fractions. 

Allocate  JacBins  to  report  airflow  solution  iterations 
Set  up  airflow  matrices  - see  af  mat  self ) 

Set  numerical  derivative  flags  - in  setNmDrv( ) 

If  using  non-trace  contaminants 

Copy  control  parameters  from  _rcdat  to  _MFn_mat 
Set  up  non-trace  mass  matrices  - see  mf  mat  setf ) 

If  using  trace  contaminants 

Copy  control  parameters  from  _rcdat  to  _MFt_mat 
Set  up  trace  mass  matrices  - see  mf  mat  set{ ) 

□ mat_term(  ) 

[function  in  file  contamx.  c] 

Free  the  allocated  matrices  for  solving  airflows  and  mass  fractions. 

All  heap  memory  allocated  in  mat  init(  ) is  freed  in  reverse  order  in  mat_term(  ).  Other  memory 
allocated  earlier  in  prj_read( ),  contamx( ),  and  main( ) is  also  freed. 

□ mf_mat  set( ) 

[function  in  file  matset.c] 

Set  up  contaminant  matrices. 

Transfer  control  parameters  from  _rcdat  to  the  structure  for  mass  fraction  calculations 
Set  up  vector  of  pointers  to  nodes  with  constant  pressure  nodes  last 
Determine  positions  of  all  non-zero  elements  in  flow  solution  matrix  - in  acolset( ) 

Allocate  and  fill  the  ijf  vector  sparse  data  mapping  - see  Sparse  Matrix  Data  Structure 
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For  the  skyline  method  for  solving  simultaneous  algebraic  equations 
Report  the  initial  matrix  profile  structure  - in  ija_prfl( ) 

Compute  new  sequence  of  equations  to  reduce  average  profile  - see  ija  optordf ) 

Reset  the  airflow  equation  numbers  in  the  node  data  structures 
Report  the  final  matrix  profile  structure  - in  ija_prfl( ) 

Allocate  remaining  arrays  depending  on  solution  method  - see  de  mat  alc( ) 

Set  pointers  for  off-diagonal  elements  in  the  link  structures 
Report  solution  notes  to  the  LOG  file 

□ prj_read( ) 

[function  in  file  prjread.c] 

Read  the  project  (PRJ)  file. 

This  and  related  functions  in  the  same  file  have  been  written  to  read  the  project  file  for 
ContamW  or  for  ContamX  depending  on  the  definition  of  the  macro  CTMW  being  1 or  zero, 
respectively.  ContamW  uses  data  such  as  sketchpad  data  and  units  for  displaying  parameters 
that  are  not  needed  in  ContamX. 

The  ContamW  version  of  prj_read( ) includes  code  for  updating  previous  versions  of  the  project 
file.  Sections  of  the  project  file  are  read  by  functions  within  the  prjread.c  file.  Sections  are 
ordered  so  that  items  referenced  by  pointers  in  the  data  structures  are  read  before  they  are 
referenced.  For  example,  a flow  path  must  refer  to  a flow  element,  so  flow  elements  are  read 
before  flow  paths.  If  a significant  error  is  encountered  while  reading  any  section,  input 
processing  is  terminated  and  an  error  code  is  returned  by  prj_read( ). 

The  ContamW  version  calls  functions  to  check  and  process  pointers  in  the  controls  because 
control  nodes  have  pointers  to  other  control  nodes.  The  ContamX  version  includes  related 
processing  for  controls  and  functions  to  create  the  airflow  network  by  converting  zones  and 
junctions  to  network  nodes  and  converting  paths  and  ducts  to  network  links  - see  sim  data(  ). 

Several  temporary  data  structures  are  allocated,  used,  and  then  freed.  For  example,  most  named 
elements  such  as  schedules,  filters,  flow  elements,  etc.,  are  stored  in  individually  allocated 
structures  with  an  allocated  vector  of  pointers  to  those  structures.  When  such  an  element  is  later 
referenced  by  sequence  number,  that  number  is  converted  to  the  pointer  to  the  element  according 
to  the  vector  of  pointers. 

□ sim_data( ) 

[function  in  file  pi  j data,  c] 

Convert  project  data  to  forms  used  for  simulation. 

Transfer  elements  from  the  _rcdat  structure  to  individual  global  variables 
Transfer  steady-state  weather  data  to  ambient  airflow  node. 

Transfer  default  contaminant  concentrations  to  ambient  airflow  node. 

Set  ductwork  junction  volumes  - in  jct_set( ) 

Set  airflow  node  data  - in  afnd_set( ) 

Set  airflow  link  data  - in  afpt_set( ) 

Define  implicit  flow  elements:  simple  AHS  and  duct  leaks 
Set  implicit  flow  paths 
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Check  completeness  of  airflow  network  - in  airnet_check( ) 

Create  linked  list  of  day-schedules 
Create  linked  list  of  week-schedules 
Complete  trance  and  non-trace  source  linked  lists 
Copy  boundary-layer  non-trace  sinks  to  separate  list 
Copy  boundary-layer  trace  sinks  to  separate  list 
Convert  occupancy  zones  to  node  pointers 
Create  linked  list  of  exposure  structures 
Complete  control  links  - see  Ctrl  iinks( ) 

j sim_init( ) 

[ function  in  file  simulate,  c] 

Initialize  flows  and  compute  steady-state  mass  fractions. 
if  using  non-trace  contaminants 

Compute  gas  constant  for  mixed  air  in  each  zone 
Compute  mass  of  air  in  each  zone 
If  using  WPC  File 

Get  wind  pressure  from  WPC  File  [in  WPC_get()] 

Compute  wind  pressures  - see  calc  WP{ ) 

Compute  stack  pressures  - see  calc  SP{ ) 

Initial  guess  for  pressures  by  linear  flow  approximation  - see  init  Af{ ) 

Reset  convergence  and  time  step  values 
Iterate  through  density  changes: 

{ 

Solve  for  airflows  by  Newton-Raphson  iteration  with 
simple  trust  region  method  - see  SolveAfstrf ) 
or  simple  under-relaxation  - see  SolveAfsurf ) 

Break  loop  if  densities  have  converged 
Tighten  N-R  convergence  for  next  iteration 
If  using  non-trace  contaminants 

Compute  non-trace  mass  fractions  [in  init_Mfn()  and  solv_DE()] 
Compute  gas  constant  for  mixed  air  in  each  zone 
Compute  mass  of  air  in  each  zone 
Re-compute  stack  pressures  - see  calc  SP( ) 

} 

Initialize  trace  and  non-trace  mass  transfer  data  - see  init  Mfn( ) and  init  Mff( ) 
Compute  trace  mass  fractions  [call  solv_DE()] 

If  not  initializing  for  transient  simulation,  report  results  - in  simout( ) 

j sim_loop( ) 

l function  in  file  simulate.c] 

Perform  transient  simulation. 

Set  parameters  to  control  output  and  time  step  loop 
Display  information  (for  DOS  window  only) 


16 


Part  2 - ContamX  Program  Structure 


While  (not  done): 

{ 

Check  for/process  user  interruption 
Initialize  daily  summary  results  as  needed 
Increment  time  of  day  by  one  time  step 
Get  contaminant  data  - see  ambtctm  get( ) 

Get  weather  data  - see  weather  qet( ) 

Compute  airflows  and  mass  fractions  for  current  time  - see  sim  step( ) 

Write  results  if  time  of  day  is  on  a listing  time  step  - in  simout( ) 

Compute  flows  for  daily  summary 

Compute  mass  fractions  for  daily  summary 

Check  for  reaching  non-cyclic  end  point  - set  done 

If  (time  = 24:00:00) 

Write  daily  summary  results 

Check  for  cyclic  convergence  - set  done 

If  (not  done) 

Advance  day  count;  reset  time  of  day  to  00:00:00 
Write  results 

Reset  read  position  in  weather  and  contaminant  files 

} 

Write  summary  results  - in  simout( ) 

Close  results  files,  weather  file,  and  contaminant  file 

□ sim_step( ) 

[function  in  file  simulate,  c] 

Simulate  a single  time-step. 

Save  mass  and  mass  fraction  values  at  end  of  last  time  step 
Set  all  schedule  values  and  process  controls  - see  Ctrl  sim( ) 

Compute  scheduled  mass  gains 
Compute  wind  pressures  - see  calc  WP( ) 

Loop  until  zone  masses  converge 

{ 

Compute  stack  pressures  - see  calc  SF( ) 

Solve  for  airflows  by  Newton-Raphson  iteration  with 

simple  trust  region  method  - see  SoiveAfstr( ) 
or  simple  under-relaxation  - see  SolveAfsur( ) 

If  using  non-trace  contaminants: 

Compute  non-trace  mass  fractions  - see  solve  Mfn( ) 
Re-compute  gas  constant  for  mixed  air  in  each  zone 
Compute  mass  in  each  zone 
Check  zone  mass  convergence 
} 

Solve  trace  species  mass  fractions  - see  solve  Mft( ) 

Compute  exposure  values 
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□ solve_DE( ) 

[function  in  file  solvde.c] 

Solve  differential  equations  by  trapezoidal  integration  and  mixed  direct/iterative  solution  of 
simultaneous  equations. 

Solve  [A]  {x}  = {b}.  Temporary  [A]  and  {b}  created  so  new  {xp}  can  be  calculated. 

□ Solve_Mfn(  ) 

[function  in  solvmfc] 

Solve  for  the  mass  fractions  of  the  non-trace  contaminants. 

This  function  uses  the  same  process  described  in  solve  Mft(  ) except  that  only  the  non-trace 
contaminants  are  considered. 

□ Solve_Mft(  ) 

/ function  in  solvmfc] 

Solve  for  the  mass  fractions  of  the  trace  contaminants. 

See  also  Solution  of  the  Species  Differential  Equations. 

If  on  the  first  iteration  during  a time  step: 

Compute  the  constant  (predictor)  portions  of  the  difference  equation 
Fill  the  [A]  matris  - in  Fill_Mf( ) 

Solve  the  difference  equations  for  values  at  the  end  of  the  time  step 
Transfer  results  to  node  and  sink  structures 

□ SolveAfstr(  ) 

[function  in  solvaf.c] 

Solve  symmetric  simultaneous  non-linear  algebraic  equations  by  Newton-Raphson  with  simple 
trust  region. 

Dr.  David  Lorenzetti  developed  this  function.  It  provides  a more  robust  algorithm  than  the 
earlier  under-relaxation  method.  It  is  the  default  method  and  should  be  used  unless  some 
particular  problem  is  encountered. 

□ SolveAfsur(  ) 

[function  in  solvaf.c] 

Solve  symmetric  simultaneous  non-linear  algebraic  equations  by  Newton-Raphson  with  simple 
under-relaxation. 

Loop  until  convergence  or  iteration  limit 

Fill  the  airflow  solution  matrix  - see  FillAff ) 

Check  convergence 

Solve  simultaneous  linear  equations  for  dP  values  - see  solve  siae( ) 

Under-relax  the  pressure  adjustments 
Adjust  the  airflow  node  pressures 
Clear  any  numerically  insignificant  airflows 

This  method  was  used  in  ContamW  1.0  and  the  earlier  DOS  versions  of  CONTAM. 
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□ solve_slae( ) 

[function  in  solvse.c] 

Solve  symmetric  simultaneous  linear  algebraic  equations. 

Select  solution  method: 

Skyline: 

Transfer  data  from  sparse  to  skyline  arrays  - in  fill_sky_s( ) 

L-U  factor  skyline  matrix  - in  luf_sky_s( ) 

Solve  simultaneous  equations  directly  - in  lus_sky_s( ) 

Preconditioned  conjugate  gradient  (PCG): 

Transfer  data  from  sparse  to  preconditioning  array  - in  fill_ssm( ) 

Perform  incomplete  Cholesky  decomposition  - in  luf_chl_c( ) 

Solve  simultaneous  equations  iteratively  - in  sa_pcg( ) 

Gauss  elimination: 

Transfer  data  from  sparse  to  full  arrays  - in  fill_ges( ) 

L-U  factor  the  full  matrix  - in  luf_ge( ) 

Solve  the  simultaneous  equations  - in  lus_ge( ) 

The  skyline  method  does  a direct  solution  using  a reduced  array.  It  is  more  reliable  than  PCG 
and  usually  faster  for  small  problems.  The  PCG  method  is  faster  for  large  problems  if  it 
converges.  The  gauss  elimination  method  is  only  to  provide  a well-established  solution  for 
comparison  with  the  other  methods.  It  is  prohibitively  slow  for  larger  problems. 

□ weather_get( ) 

[function  in  file  weather,  c] 

Get  the  weather  file  data  for  the  current  simulation  time. 

Note:  the  weather  structure  defined  in  weather.c  hold  data  for  computing  the  weather  data  at  the 
current  simulation  time  (_sim_time)  from  data  in  the  weather  file  at  the  times  (timeO  and  timel) 
that  bound  the  _sim_time. 

Set  the  weather  file  pointer 
Reset  time  at  end-of-day 

Read  the  weather  file  until  timeO  < _sim_time  <=  timel 

Reset  timeO  and  corresponding  data  as  necessary 
Check  the  data  date 

Read  and  store  the  time  and  corresponding  data 
Reset  wind  direction  for  interpolation 

Set  weather  data  for  current  simulation;  use  linear  interpolation  if  not  at  timel 
Convert  ASHRAE  humidity  ration  to  Contam  mass  fraction  of  H20 
Transfer  data  to  global  variables 

□ weather_init( ) 

[function  in  file  weather.c] 

Initial  processing  of  the  weather  file. 

Open  the  weather  file  - using  nxtopen( ) 

Confirm  file  type  and  version 
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Read  the  weather  file  start  and  end  dates 

Confirm  simulation  dates  within  weather  file  dates 

Read  and  store  day-of-week,  day-type,  DST,  and  Tg  for  all  dates 

Position  weather  file  at  the  simulation  start  date 

Set  day-data  globals:  _daytyp,  _dayofw,  _DSTind 

Read  and  store  weather  data  for  time  00:00:00 

For  cyclic  simulation  save  position  in  weather  file  of  first  time  step 

The  weather  and  contaminant  files  are  read  using  the  nxtword( ) utility  function.  This  requires 
that  the  _unxt  file  pointer  be  set  to  the  weather  file  or  the  contaminant  file  before  each  is  read. 

2.3.3  Utility  Functions 

Compiler  dependent  functions  have  been  grouped  in  file  config.c.  Memory  allocation  and  de- 
allocation functions  are  in  file  heap.c.  Other  utility  functions  are  in  file  utils.c.  Three  different 
compilers  have  been  used  - two  for  the  earlier  DOS-based  CONTAM93  and  CONTAM96 
programs,  and  Visual  C++  versions  6.0  and  .NET  for  the  current  MS  Windows  based  program. 

□ File  path  processing 

[functions  in  file  config.c] 

These  functions  are  used  to  create  output  file  paths  that  will  open  in  the  proper  directory. 
pathsplit(  ) converts  a path  into  its  component  parts  (drive,  directory,  name,  and  extension). 
pathmerge(  ) does  the  opposite. 

□ Error  handling 

[functions  in  file  config.c] 

Error  messages  are  generated  by  a call  to  the  error(  ) function.  Passed  parameters  include  the 
severity  of  the  error,  the  name  and  line  number  of  the  file  from  which  error(  ) is  called,  and  an 
indefinite  number  of  strings  describing  the  error.  The  function  maintains  a count  of ‘‘severe' 
errors.  The  global  variable  emode  (in  setEmode( ))  controls  display  of  the  error  message. 

If  severity  >=  0,  the  function  will  merge  the  message  strings  into  a single  string  and  create 
another  string  reporting  the  file  name  and  line  number  - i.e.,  the  source  of  the  error.  The 
severity,  source,  and  error  message  are  then  displayed  in  a dialog  box  or  the  DOS  window 
depending  on  emode,  and  they  are  written  to  the  LOG  file. 

If  severity  > 2,  ContamX  will  be  terminated  by  calling  finish(  ) which  also  closes  all  open  files. 

If  severity  = 2,  the  count  of  severe  errors  is  incremented. 

If  severity  < -1 , the  count  of  severe  errors  is  reset  to  zero. 

If  severity  = -1,  the  only  action  is  to  return  the  current  count  of  severe  errors. 

If  the  count  of  severe  errors  reaches  10  and  the  dialog  box  is  in  effect,  the  user  will  be  asked  if  he 
wants  to  terminate  the  simulation.  If  he  does  not,  the  count  of  severe  errors  is  reset  to  zero. 

This  prevents  an  endless  display  of  error  messages  that  could  occur  in  some  circumstances. 


20 


Part  2 - ContamX  Program  Structure 


The  lognote(  ) function  is  used  to  write  similar  informative  messages  to  the  LOG  file  only.  It  is 
a debugging  tool  not  intended  to  be  informative  to  the  general  ContamX  user. 

□ Console  input 

[functions  in  file  config.c] 

getkey(  ) is  used  to  read  a single  keystroke.  The  wait  parameter  tells  getkey(  ) to  wait  until  a 
key  is  pressed  or  to  return  immediately  if  a key  has  not  been  pressed. 

noyes(  ) obtains  a no  or  yes  response  to  a query.  It  returns  0 for  no  or  1 for  yes.  The  query  is 
presented  in  a dialog  box  or  the  DOS  window  depending  on  emode. 

□ Heap  tests 

/ functions  in  file  config.c] 

memrem(  ) reports  the  memory  still  available  in  the  heap.  It  is  useful  for  determining  if  heap 
memory  has  been  properly  freed.  It  works  with  the  Borland  and  Watcom  compilers  but  is  not 
available  in  Visual  C++. 

memwalk(  ) reports  the  status  of  the  allocated  heap  memory  and  then  displays  the  status  of  every 
heap  allocation.  This  seems  to  not  be  working  with  the  current  Visual  C++. 

nptest(  ) reports  if  a value  has  been  written  to  address  0.  This  occurs  when  a value  is  written  to  a 
null  pointer.  The  test  is  not  applicable  to  Visual  C++. 

□ Math  error  processing 

[functions  in  file  config.c] 

flterr(  ) and  matherr(  ) trap  various  floating  point  errors,  print  error  messages,  and  terminate  the 
program. 

□ Heap  processing 

[functions  in  file  heap.c] 

All  memory  allocations  and  de-allocations  should  go  through  alc_e(  ) and  fre_e( ) to  allow  some 
useful  heap  checking  options  based  on  the  definition  of  the  macro  MEMTEST:  1 = test  guard 
bytes;  2 = log  actions;  and  0 = no  tests.  When  MEMTEST  > 0,  four  guard  bytes  are  added 
before  and  after  the  normal  heap  memory  allocation.  These  guard  bytes  are  used  to  test  writes 
and  reads  beyond  the  ends  of  the  allocated  vector  — especially  useful  for  off-by-one  indexing. 
Based  on  an  idea  and  code  by  Paul  Anderson,  "Dr.  Dobb's  C Sourcebook",  Winter  1989/90,  pp 
62  - 66,  94.  When  MEMTEST  > 1,  every  allocation  and  de-allocation  is  reported  in  the  LOG 
file. 

alc_e( ),  fre_e(  ),  and  chk_e(  ) allocate,  de-allocate,  and  check  the  guard  bytes  of  a single  block 
of  memory.  The  check  is  automatically  performed  at  de-allocation. 

alc_mc(  ),  fre_mc(  ),  and  chk_mc( ) allocate,  de-allocate,  and  check  a rectangular  matrix  (2- 
dimensional  array)  given  minimum  and  maximum  row  and  column  indices.  Memory  is  allocated 
contiguously. 

alc_mvc(  ),  fre_mvc(  ),  and  chk_mvc(  ) allocate,  de-allocate,  and  check  a matrix  with  variable 
length  rows  (used  to  store  skyline  method  coefficients). 
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alc_v( ),  fre_v(  ),  and  chk_v(  ) allocate,  de-allocate,  and  check  a vector  (2-dimensional  array) 
given  the  minimum  and  maximum  indices. 

alc_ec(  ),  fre_ec(  ),  and  alc_eci(  ) speed  and  simplify  allocation  and  de-allocation  for  many 
small  structures  such  as  the  Contain  zones,  paths,  schedules,  flow  elements,  etc.  Small  structures 
are  ‘allocated'  within  a larger  allocated  block  which  is  initially  created  with  alc_eci( ).  A single 
call  to  fre_ec( ) will  de-allocate  the  entire  block;  individual  structures  cannot  be  freed.  This 
saves  quite  a bit  of  memory  allocation  overhead  and  is  quite  a bit  faster  than  calling  alloc( ) for 
each  small  structure.  Based  on  an  idea  and  code  by  Steve  Weller,  "The  C Users  Journal",  April 
1990,  pp  103  - 107. 

□ Text  File  Reading  Functions 

[functions  in  file  uti/s.c] 

nxtopen(  ),  nxtline(  ),  nxtwrd(  ),  and  nxtclose(  ) are  used  to  process  the  project,  weather,  and 
contaminant  ASCII  text  data  files.  These  functions  process  the  file  designated  FILE  *_unxt.  A 
key  feature  of  these  functions  is  their  handling  of  erroneous  input  values. 

□ Format  Conversion  Functions 

[functions  in  file  uti/s.c] 

db!con(  ) converts  a string  to  an  8-byte  real  variable. 

fltcon(  ) converts  a string  to  a 4-byte  real  variable. 

longcon(  ) converts  a string  to  a 4-byte  integer  variable. 

intcon(  ) converts  a string  to  a default  size  integer  variable. 

timecon(  ) converts  a string  (hh:mm:ss)  to  seconds  past  midnight. 

datecon(  ) converts  a string  (dd/mm,  mm/dd)  to  a day-of-year  number  (1  - 365). 

datxcon(  ) converts  a string  (mm/dd)  to  a day-of-year  number  (1  - 365)  (for  Excel 
compatibility). 

fltstr(  ) converts  a 4-byte  real  variable  to  a string. 
intstr( ) converts  a 4-byte  integer  variable  to  a string. 

timestr(  ) converts  a 4-byte  integer  (seconds  past  midnight)  to  a string  of  the  form:  hh:mm:ss. 

datestr(  ) converts  a day-of-year  integer  (1  - 365)  to  a string  (ddmm). 

datxstr(  ) converts  a day-of-year  (1  - 365)  to  a string  (dd/mm)  (for  Excel  compatibility). 

□ Input  Conversion  Functions 

[functions  in  file  uti/s.c] 

readR8(  ) reads  the  next  word  from  file  unxt  and  converts  it  to  an  8-byte  real  variable. 
readR4(  ) reads  the  next  word  from  file  unxt  and  converts  it  to  a 4-byte  real  variable. 
readI4(  ) reads  the  next  word  from  file  unxt  and  converts  it  to  a 4-byte  integer  variable. 
readI2(  ) reads  the  next  word  from  file  unxt  and  converts  it  to  a default  size  integer  variable. 
readHMS( ) reads  the  next  word  from  file  unxt  and  converts  it  to  a 4-byte  integer  time  value. 
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readMD(  ) reads  the  next  word  (ddmm,  mmdd)  from  file  unxt  and  converts  it  to  a day-of-year 
number  (1  - 365). 

readMDx(  ) reads  the  next  word  (dd/mm)  from  file  unxt  and  converts  it  to  a day-of-year 
number  (1  - 365). 

The  ‘‘default  size"  integer  is  2-bytes  for  a 16  bit  compiler  and  4-bytes  for  a 32  bit  compiler. 
CONTAM  presently  enforces  the  rule  that  such  an  integer  must  be  in  the  range  -32767  to 
+32767,  i.e.,  fits  in  a 2-byte  integer.  This  limits  the  maximum  number  of  zones,  paths,  etc.,  to 
32767.  Relaxing  this  limit  will  also  require  the  conversion  of  small  integers  in  the  data 
structures. 

2.3.4  Sparse  Matrix  Data  Structure 

Calculation  of  both  the  airflows  and  mass  fractions  involve  solving  simultaneous  linear  algebraic 
equations.  These  simultaneous  equations  can  be  expressed  in  matrix  form:  [A]  {x}  = {b}  where 
{b}  is  an  N-element  vector,  [A|  is  an  N by  N matrix,  and  the  solution  {x}  is  an  N-element  vector. 
As  N gets  large  (CONTAM  projects  with  over  3000  nodes  have  been  created)  the  size  of  A 
becomes  excessive  and  the  execution  time  using  full  matrix  methods  becomes  even  more 
excessive.  When  N is  large  only  a small  portion  of  elements  of  A are  non-zero,  therefore  sparse 
matrix  techniques  should  be  used  to  solve  such  problems.  There  are  also  methods  to  store  only 
the  non-zero  elements  of  A. 

Press  et  al.  [8  p78]  present  a good  method  for  storing  sparse  matrices: 

"To  represent  a matrix  A of  dimension  N x N,  the  row- indexed  scheme  sets  up  two  one- 
dimensional arrays,  call  them  sa  and  ija.  The  first  of  these  stores  matrix  element  values  in  single 
or  double  precision  as  desired;  the  second  stores  integer  values.  The  storage  rules  are: 

• The  first  N locations  of  sa  store  A's  diagonal  matrix  elements  in  order.  (Note  that  diagonal 
elements  are  stored  even  if  they  are  zero;  this  is  at  most  a slight  storage  inefficiency,  since 
diagonal  elements  are  nonzero  in  most  realistic  applications.) 

• Each  of  the  first  N locations  of  ija  stores  the  index  of  the  array  sa  that  contains  the  first  off- 
diagonal  element  of  the  corresponding  row  of  the  matrix.  (If  there  are  no  off-diagonal  elements 
for  that  row,  it  is  one  greater  than  the  index  in  sa  of  the  most  recently  stored  element  of  a 
previous  row.) 

• Location  1 of  ija  is  always  equal  to  N + 2.  (It  can  be  read  to  determine  N.) 

• Location  N + 1 of  ija  is  one  greater  than  the  index  in  sa  of  the  last  off-diagonal  element  of  the 
last  row.  (It  can  be  read  to  determine  the  number  of  nonzero  elements  in  the  matrix,  or  the 
number  of  elements  in  the  arrays  sa  and  ija.)  Location  N + 1 of  sa  is  not  used  and  can  be  set 
arbitrarily. 

• Entries  in  sa  at  locations  > N + 2 contain  A's  off-diagonal  values,  ordered  by  rows  and,  within 
each  row,  ordered  by  columns. 

• Entries  in  ija  at  locations  > N + 2 contain  the  column  number  of  the  corresponding  element  in 
sa ." 

In  ContamX  the  coefficients  for  the  airflow  Jacobian  and  for  the  mass  fraction  calculations  are 
first  stored  into  this  sparse  structure.  They  may  then  be  transferred  to  another  data  structure 
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designed  for  the  solution  algorithm  being  employed.  There  is  a small  run-time  overhead  for  this 
process,  but  it  is  very  flexible  when  it  is  not  known  that  a single  best  solution  method  exists  for 
all  cases. 

2.3.5  Solution  of  the  Species  Differential  Equations: 

The  transient  evolution  of  the  node  contaminant  masses  and  mass  fractions  are  determined  in  a 
the  following  manner.  It  is  expressed  in  terms  of  {Q} 

{Q}  = [C]{X}  (1) 

where  {Q}  is  the  vector  of  masses  of  all  species  in  all  nodes,  [C]  is  a diagonal  matrix  of  node  air 
masses,  and  {X}  is  the  vector  of  mass  fractions. 

The  basic  time  discretization  is 

{Q},  ~{0_*+{0A/  (2) 

where  the  following  linear  approximation  will  be  used: 

{Q}=[K]{X}  + {G}  (3) 

[AT|  is  the  matrix  of  inter-nodal  mass  flows  (and  reactions),  and  { G } is  the  vector  of  net  mass 
generation  rates.  For  large  problems  [AT]  will  be  sparse. 

Equation  (3)  will  be  solved  using  a trapezoidal  approximation  of  the  derivative  term: 

{ Q ),  = w,.*  + (i  - r)A/{0,.4,  + r a m,  (4) 

where  y is  a parameter  controlling  the  stability  and  accuracy  of  the  integration: 

y = 0 corresponds  to  the  standard  explicit  method, 

y = 1/2  corresponds  to  the  Crank-Nicholson  method, 

y = 2/3  corresponds  to  the  Galerkin  method,  and 

y = 1 corresponds  to  the  standard  implicit  method. 

y must  be  greater  than  or  equal  to  0.5  for  unconditional  stability,  although  values  below  about 
0.75  may  show  oscillations. 

Equation  (4)  can  be  rearranged  as 

{Q},  = {0(_*  + yM{Q},  (5) 

where 

{0,-a,  ={0,-*+(i-r)A/{0_*  (6) 

is  a quantity  based  entirely  on  values  known  at  end  of  the  last  time  step,  time  t-At. 

Equation  (5)  can  be  converted  into  the  form  to  solve  for  {X> : 

[A}{X}  = {B]  (7) 


with 


M]  = [C],  -yM[K\ 


(8) 
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and 

{B}  = {Q}l_AI+rAt{G}l  (9) 

In  equation  (8)  there  appears  to  be  the  possibility  of  a coefficient  on  the  diagonal  of  [A]  going  to 
zero.  This  should  not  happen  because  kn,n  < 0 (and  kn,m  > 0)  which  forces  an  n > 0 (and  an  m < 0). 

I lie  only  possible  problem  is  in  the  case  of  an  isolated  node,  kn,n  = 0,  that  is  also  massless,  cn  = 0, 
which  will  require  special  handling. 

Note  on  derivation  of  equations  (7)  - (9)  from  equation  (5): 

[C],  {X},  = {£>},_,,  + r&([K],{X}l  + {G},)  (10) 

{[Cl-yM[K],){X},  ~{Q},^  + rAt{G},  (11) 

2. 3. 5. 1 Special  Cases 

( I ) A steady  state  solution  for  {X}  is  obtained  by  rearranging  equation  (3): 

[K]{X}  = -{G}  (12) 

( 2 ) cn  = 0 (massless  node) 

There  is  no  transient  storage  effect,  therefore  xn  at  time  t is  determined  by  the  flows  into  the  node 
at  that  time.  This  is  equivalent  to  the  steady-state  solution  of  equation  (12). 

( 3)  kn,n  = 0 (no  flow  - isolated  node) 

l or  cn  > 0,  the  cn  term  in  the  coefficient  on  the  diagonal  (see  equation  (11))  will  prevent  division 
by  zero. 

l or  cn  = 0,  solution  of  equation  (1 1)  will  lead  to  a division  by  zero.  The  practical  solution  is  to 
alter  the  coefficients  in  [A]  and  { B}  so  that  xn,t  will  be  xn,t-At  after  solving  equation  (7).  That  is, 
a„  „ = 1 , an,m  = 0 for  all  m,  and  b„  = xn,t-At- 

2. 3. 5. 2 Numerical  Methods 

ContamX  2 includes  several  methods  for  solving  equation  (7),  which  represents  a set  of 
equations  that  are  linear,  non-symmetric,  and  diagonally  dominant.  The  direct  solvers  are  Gauss 
elimination  (for  test  purposes  only)  and  a non-symmetric  skyline  method  for  practical 
computations.  The  performance  of  the  latter  can  depend  on  the  ordering  of  the  equations.  It  uses 
the  TOMS  586  algorithm  to  improve  that  ordering.  This  is  possible  because  the  structure  of  [A] 
is  symmetric  even  though  the  coefficients  are  not.  Two  iterative  methods  are  available:  a bi- 
conjugate gradient  technique  which  currently  has  a problem  when  {X}  = 0,  and  a simple 
successive  over-relaxation  (SOR)  method.  The  iterative  methods  require  less  memory  than  the 
direct  methods,  but  may  or  may  not  be  faster  depending  on  the  matrix  size,  sparsity  pattern,  and 
the  number  of  iterations  for  convergence. 
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2.4  CONTAM  Input  and  Output  Files 

This  section  provides  detailed  information  of  the  files  used  by  ContamX  and  ContamW. 

2.4.1  Project  File  (.PRJ) 

CONTAM  2 consists  of  two  separate  programs:  ContamW  provides  the  graphic  user  interface 
for  describing  the  building  and  viewing  simulation  results;  ContamX  performs  the  simulation. 
'‘Project' * files  (.PRJ  extension)  provide  input  to  both  ContamW  and  ContamX.  Project  files  are 
created  by  the  functions  in  file  prjsave.c  in  ContamW  and  read  by  the  functions  in  file  prjread.c 
in  ContamW  and  ContamX.  The  project  file  contains  some  information  that  is  used  only  by 
ContamW  and  not  by  ContamX,  e.g.,  input  units  and  the  SketchPad  display  data.  These  data  are 
read  when  the  macro  name  CTMW  is  defined  to  be  1,  and  they  are  not  read  when  it  is  defined  to 
be  0. 

Most  of  the  data  are  read  into  structures  that  are  defined  in  the  files  contam.h  and  celmts.h  for 
ContamW  and  files  simdat.h  and  selmts.h  for  ContamX.  Some  data  are  read  into  global 
variables  that  are  defined  in  cglob.h  and  cxtm.h  for  ContamW  and  sglob.h  and  sxtrn.h  for 
ContamX.  These  variables  are  indicated  by  a leading  underscore.  in  their  name. 

One  important  feature  of  the  project  files  is  the  tremendous  variety  of  data  stored.  It  has  been 
divided  into  sections  grouping  similar  kinds  of  data,  or  objects,  together.  Each  section  is 
terminated  with  the  special  value  -999  which  serves  as  a check  for  some  reading  errors.  Within 
each  section  there  are  usually  multiple  objects,  each  stored  into  an  individual  structure.  Such  a 
section  begins  with  the  number  of  objects  and  starts  the  data  for  each  object  with  a sequence 
number  that  serves  to  check  for  reading  errors.  These  objects  may  be  ordered  as  arrays  when  the 
total  number  is  constant,  or  as  linked  lists  to  allow  the  number  to  vary. 

In  the  following  material  individual  variables  are  briefly  described.  Units  are  indicated  within 
brackets,  [ ].  The  type  of  variable  is  in  parentheses  (matching  the  definitions  in  the  include  file 
types. h). 

12  - a two-byte  long  signed  integer  (C  type  "short") 

14  - a four-byte  long  signed  integer  (C  type  "long") 

IX  - a default  length  signed  integer  (C  type  “inf ') 

UX  - a default  length  unsigned  integer  (C  type  "unsigned") 

R4  - a four-byte  long  real  (C  type  “float") 

R8  - an  eight-byte  long  real  (C  type  "double") 

Variables  used  only  by  ContamW  are  indicated  by  {W}. 

Each  section  includes  sample  data  from  the  Sample!  1 .prj  file.  This  file  includes  samples  of  all 
the  different  flow  and  source  element  types.  Only  part  of  Section  3 is  shown  (...)  to  save  space. 
A simulation  of  the  Sample!  1 .prj  project  file  can  be  run,  but  the  results  are  not  very  meaningful. 

Comments  are  included  in  the  project  file  to  make  it  somewhat  human-readable.  Anything  after 
an  exclamation  mark,  !,  to  the  end  of  the  line  is  not  read  by  the  input  processor. 
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2.4. 1. 1 Sections  of  the  PRJ  file: 

Section  1 : Project.  Weather.  Simulation,  and  Output  Controls 

Section  2:  Species  and  Contaminants 
Section  3:  Level  and  Icon  Data 
Section  4:  Day  Schedules 
Section  5:  Week  Schedules 
Section  6:  Wind  Pressure  Profiles 
Section  7:  Kinetic  Reactions 
Section  8:  Filters 
Section  9:  Source/Sink  Elements 
Section  10:  Airflow  Elements 
Section  1 1 : Duct  Elements 
Section  12:  Control  Nodes 
Section  13:  Simple  AHS 
Section  14:  Zones 

Section  15:  Initial  Zone  Concentrations 

Section  16:  Airflow  Paths 

Section  17:  Duct  Junctions 

Section  18:  Initial  Junction  Concentrations 

Section  19:  Duct  Segments 

Section  20:  Sources/Sinks 

Section  2 1 : Occupancy  Schedules 

Section  22:  Exposures 

Section  23:  Annotations 
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j Section  1:  Project,  Weather,  Simulation,  and  Output  Controls 

C omment  lines  are  added  by  ContamW  (see  example)  to  help  visually  identify  the  parameters. 

I he  first  line  of  the  project  file  identifies  the  source  program: 

* ring  []  //  program  name  should  be  "ContamW"  (II) 

' ring  []  //  program  version  should  be  "2.0"  (II) 

:ho  //  (0/1)  echo  input  files  to  the  log  file  (12) 


I he  second  line  is  a user-defined  description  of  the  project: 

r rjdesc[]  //  (unused)  project  description  (II)  { W } 

l he  next  line  sets  the  following  miscellaneous  values: 


skwidth 

// 

total  SketchPad  width  [cells]  (12) 

{w} 

skheight 

// 

total  SketchPad  height 

[cells]  (12) 

{w} 

lef  units 

// 

default  units:  0 = SI, 

1 = US  (12) 

{«} 

ief  flows 

// 

default  flows:  0 = mass 

, 1 = volume 

(12)  {W} 

ief_T 

// 

default  temperature  for 

zones  [K]  ( 

R4 ) {W} 

udefT 

// 

units  for  temperature 

(12)  {W} 

rel_N 

// 

angle  to  true  north  [degrees]  (R4) 

{w} 

wind  H 

// 

elevation  for  reference 

wind  speed 

[m]  (R4 ) {W} 

uwH 

// 

units  for  wind  H (12) 

{ w} 

wind  Ao 

// 

local  terrain  constant 

(R4)  {W} 

wind  a 

// 

velocity  profile  exponent  (R4)  {w} 

The  next  line  defines  the  weather  (WTHDAT)  for  steady-state  simulation  in  ContamX: 

R4  ) 

NOT  corrected  to  sea  level  (R4 


Tambt 

// 

ba  rpres 

// 

windspd 

// 

wunddir 

// 

re  1 hum 

// 

daytyp 

// 

uTa 

// 

ubP 

// 

uws 

// 

uwd 

// 

ambient  temperature  [K] 
barometric  pressure  [Pa] 
wind  speed  [m/s]  (R4) 

wind  direction:  0 = N,  90  = 
relative  humidity:  0.0  to  1 
type  of  day  (1-12)  (12) 

units  for  Tambt  (12)  { W } 

units  for  barpres  (12)  { W } 

units  for  windspd  (12)  { W } 

//  units  for  winddir  (12)  { W } 


180  = S, 
:R4) 


;r4 


The  next  line  defines  weather  data  (WTHDAT)  for  the  wind  pressure  test  in  ContamW: 

bient  temperature  [K]  (R4)  { W } 

rometric  pressure  [Pa]  NOT  corrected  to  sea  level  (R4) 
nd  speed  [m/s]  (R4)  { W } 


Tambt 

// 

barpres 

// 

windspd 

/ / 

winddir 

/ / 

relhum 

// 

daytyp 

// 

uTa 

// 

ubP 

// 

uws 

// 

uwd 

// 

The  next 

two  lines 

{»} 


180  = S 
:R4)  {w} 


:r4)  {w} 


type  of  day  (1-12)  (12)  {w} 

units  for  Tambt  (12)  { W } 

units  for  barpres  (12)  {w} 

units  for  windspd  (12)  { W } 

units  for  winddir  (12)  {w} 


_WTHpath [_MAX_PATH]  // 
_CTMpath [_MAX_PATH]  // 
_CVFpath [_MAX_PATH]  // 
DVFpath [ MAX  PATH]  // 


full  name  of  weather  file  (II) 
full  name  of  contaminant  file  (II) 

full  name  of  continuous  values  file  (II)  {Contam  2.1} 
full  name  of  discrete  values  file  (II)  {Contam  2.1} 
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The  following  lines  define  path  location  data  (PLDDAT)  for  the  creating  the  WPC  file: 
{ Contain  2. 1} 

_WPCf ile [_MAX_PATH]  //  full  name  of  WPC  file  (II) 

EWCf ile [_MAX  PATH]  //  full  name  of  EWC  data  source  file  (II)  (w) 

WPCdesc  [] 

XO 
YO 
ZO 

angle 
u_XYZ 
epsPath 
epsSpcs 
tShif t 
dStart 
dEnd 

_useWPCwp 
_useWPCmf 

The  next  line  defines  the  location  (LOCDAT)  (for future  use  with  thermal  simulation): 


latd 

// 

latitude 

(degrees: 

north  +,  south  -) 

(R4 ) 

Igtd 

// 

longitude 

(degrees : 

east  +,  west  -) 

(R4 ) 

Tznr 

// 

time  zone 

(Greenwich  = 0,  Eastern  = 

- 5 , etc 

altd 

// 

elevation 

above  sea 

level  [m]  (R4) 

Tgrnd 

// 

ground  temperature 

[K]  (R4 ) 

utg 

// 

units  for 

ground  temperatures  (12) 

u a 

// 

units  for 

elevation 

(12) 

II  WPC  description  (II)  { W } 

//  X-value  of  ContamW  origin  in  EWC  coordinates  [m]  (R4)  {w} 

//  Y-value  of  ContamW  origin  in  EWC  coordinates  [m]  (R4)  { W } 

//  Z-value  of  ContamW  origin  in  EWC  coordinates  [m]  (R4)  { W } 

//  Rotation  of  ContamW  relative  to  EWC  coordinates  (R4)  {w} 

//  units  of  coordinates  (12)  {w} 

//  tolerance  for  matching  path  locations  [-]  (R4)  {w} 

//  tolerance  for  matching  species  [-]  (R4)  {w} 

//  time  shift  of  EWC  data  { W } [s]  (hh:mm:ss  — ■»  IX)  {w} 

//  date  WPC  data  starts  (12)  { W } 

//  date  WPC  data  ends  (12)  {w} 

//  if  true,  use  WPC  file  wind  pressures  (12) 

//  if  true,  use  WPC  file  mass  fractions  (12) 


The  remaining  data  is  stored  in  the  run  control  (RCDAT)  structure.  In  ContamX some  values 
may  be  transferred  to  other  variables  before  being  used.  The  next  two  lines  control  the  airflow 
simulation  - first  the  nonlinear  part: 


sim_af  //  airflow  simulation:'  0 = steady,  1 = dynamic  (12) 

afcalc  //  N-R  method  for  non-linear  eqns : 0 = SUR,  1 = STR 

afmaxi  //  maximum  number  of  N-R  iterations  (12) 

afrcnvg  //  relative  airflow  convergence  factor  (R4) 

afacnvg  //  absolute  airflow  convergence  factor  [kg/s]  (R4) 

afrelax  //  flow  under-relaxation  coefficient  (for  SUR)  (R4) 

uac2  //  units  for  afacnvg  (12) 


12 


and  then  the  linear  part: 

afslae  //  method  for  linear  equations:  0 = SKY,  1 = PCG  (12) 

aflmaxi  //  maximum  number  of  iterations  (PCG)  (12) 

aflcnvg  //  relative  convergence  factor  for  (PCG)  (R4) 

afrseq  //  if  true,  resequence  the  linear  equations  (12) 

aflinit  //  if  true,  do  linear  airflow  initialization  (12) 

Tadj  //  if  true,  use  temperature  adjustment  (12) 


The  next  three  lines  control  the  mass  fraction  calculation  - first  for  cyclic  simulation: 


sim_mf 

ccmaxi 

ccrcnvg 

ccacnvg 

ccrelax 


//  mass  fraction  (contaminant)  simulation: 

//  0 = none,  1 = steady,  2 = transient,  3 = cyclic  (12) 
//  simulation:  maximum  number  of  cyclic  iterations  (12) 
//  relative  convergence  factor  (R4) 

//  absolute  convergence  factor  [kg/kg]  (R4) 

//  (unused)  over-relaxation  coefficient  (R4) 
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uccc  //  units  for  ccacnvg  (12) 


then  for  non-trace  contaminants: 


mf nmthd 
mf nmaxi 
mf nrcnvg 
mf nacnvg 
mf nrelax 
mf ngamma 
uccn 


//  simulation:  0 = SKY,  1 = BCG,  2 = SOR 
//  maximum  iterations  (12) 

//  desired  relative  convergence  (R4) 

//  desired  absolute  convergence  (R4) 

//  relaxation  coefficient  (R4) 

//  trapezoidal  integration  factor  (R4) 

//  units  for  mf nacnvg  (12) 


(12) 


and  then  for  trace  contaminants: 

mftmthd  //  0 = SKY,  1 = BCG,  2 = SOR  (12) 

mftmaxi  //  maximum  iterations  (12) 

mftrcnvg  //  desired  relative  convergence  (R4) 

mftacnvg  //  desired  absolute  convergence  (R4) 

mftrelax  //  relaxation  coefficient  (R4) 

mftgamma  //  trapezoidal  integration  factor  (R4) 

ucct  //  units  for  mftacnvg  (12) 

The  next  line  has  four  parameters;  only  the  ones  relating  to  density  changes  are  active: 

sim_vt  //  (inactive)  (0/1)  variable  zone  temperature  simulation  (12) 

tsdens  //  (0/1)  vary  density  during  time  step  (12) 

ts.relax  //  (inactive)  under- relaxation  factor  for  calculating  dM/dt  (R4) 

tsmaxi  //  maximum  number  of  iterations  for  density  changes  (12) 

The  next  line  sets  the  dates,  times,  and  time  steps  for  simulation: 

date_st  //  day-of-year  to  start  steady  simulation  (mmmdd  — ■»  IX) 

time_st  //  time-of-day  to  start  steady  simulation  (hh:mm:ss  — » 14) 

date_0  //  day-of-year  to  start  transient  simulation  (mmmdd  — » IX) 

time_0  //  time-of-day  to  start  transient  simulation  (hh:mm:ss  — > 14) 

date_l  //  day-of-year  to  end  transient  simulation  (mmmdd  —>  IX) 

time_l  //  time-of-day  to  end  transient  simulation  (hh:mm:ss  — > 14) 

time_step  //  simulation  time  step  [s]  (hh:tnm:ss  — > IX) 

time_list  //  listing  (results)  time  step  [s]  (hh:mm:ss  — > IX) 

time_scrn  //  screen  time  step  [s]  (up  to  1 day)  (hh:mm:ss  — > 14) 

The  next  line  controls  the  use  of  the  restart  fde: 

restart  //  use  restart  file  (12) 

rstdate  //  restart  date  (mmmdd  -4  IX) 

rsttime  //  restart  time  (hh:mm:ss  -a  14) 


The  remaining  parameters  control  the  simulation  outputs.  They  are  in  global  variables  in 
ContamX  and  the  savef]  vector  in  ContamW for  flexibility.  They  may  be  spread  over  several 
lines: 

_list  //  data  dump  parameter  (12) 


//  > 

0 

dump  matrix  analysis, 

//  = 

2 

dump  SIM  file  output, 

//  > 

2 

dump  lognotes. 

pf save 

/ 

save [0] 

// 

(0/1)  save  path 

flow 

results 

to 

SIM 

file  ( 11 ) 

zf save 

/ 

save [1] 

// 

(0/1)  save  zone 

flow 

results 

to 

SIM 

file  (11) 

zcsave 

/ 

save [2] 

// 

(0/1)  save  mass 

fraction  results 

to 

SIM  file  (11) 

achvol 

/ 

save  [3 ] 

// 

(0/1)  ACH  based 

on  true  volumes 

instead  of  std  volumes 
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achsave 

/ 

save [4] 

// 

(0/1) 

abwsave 

/ 

save [5] 

// 

(0/1) 

cbwsave 

/ 

save [6] 

// 

(0/1) 

exp save 

/ 

save [7] 

// 

(0/1) 

ebwsave 

/ 

save [8] 

// 

(0/1) 

zaasave 

/ 

save  [9] 

// 

(0/1) 

zbwsave 

/ 

save  [10] 

// 

(0/1) 

save [11-3 

0] 

//  (unused; 

; value 

save [31] 

//  ContamW 

will  c 

save  building  air  exchange  rate  transient  data 

save  air  exchange  rate  box-whisker  data 

save  contaminant  box-whisker  data 

save  exposure  transient  data 

save  exposure  box-whisker  data 

save  zones  age-of-air  transient  data 

save  zones  age-of-air  box-whisker  data 


ID 


ID 

{w} 


The  run  control  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 


Note  on  outputs:  _pfsave  and  zfsave  always  have  the  same  value  - 0 or  1 . The  summaries, 
save[3]  to  saveflO]  are  not  currently  active.  They  were  developed  for  Contam96  to  summarize 
the  results  of  long  simulations. 


Example: 

ContamW  2.1  0 

Test  CONTAMW  for  proper  display  of  all  elements. 

! rows  cols  ud  uf  T uT  N wH  u Ao  a 

58  66  0 0 296.150  2 0.00  10.00  0 0.600  0.280 

! Ta  Pb  Ws  Wd  rh  day  u.  . 

293.150  101325.0  0.000  0.0  0.500  12001  ! steady  simulation 

293.150  101325.0  1.000  270.0  0.000  12001  ! wind  pressure  test 

null  ! no  weather  file 

null  i no  contaminant  file 

null  ! no  continuous  values  file 

null  ! no  discrete  values  file 

null  ! no  WPC  file 

null  ! no  EWC  file 

WPC  description 

1 Xref  Yref  Zref  angle  u 

0.000  0.000  0.000  0.00  0 

I epsP  epsS  tShift  dStart  dEnd  wp  mf 
0.01  0.01  00:00:00  l/l  l/l  0 0 

! latd  longtd  tznr  altd  Tgrnd  u. . 

40.00  -90.00  -6.00  0 283.15  2 0 


!sim_af  afcalc  afmaxi  afrcnvg  afacnvg  af relax  uac 

1 1 30  0.0001  le- 005  0.75  0 

! afslae  aflmaxi  aflcnvg  afrseq  aflinit  Tadj 

0 100  le- 006  1 10 

!sim_mf  method  maxi  relcnvg  abscnvg  relax  gamma  ucc 

2 30  1 . 00e-004  1.00e-005  1.250  0 ! 

0 100  1.00e-006  1.00e-015  1.100  1.000  0 ! 

0 100  1.00e-006  1.00e-015  1.100  1.000  0 ! 

isim_vt  tsdens  relax  tsmaxi 
0 0 0.75  20 


(cyclic) 
(non- trace ) 
(trace ) 


!date_st  time_st  date_0  time_0  date_l  time_l  t_step  t_list  t_scrn 

JanOl  00:00:00  JanOl  00:00:00  JanOl  24:00:00  01:00:00  01:00:00  01:00:00 
! restart  date  time 

0 JanOl  00:00:00 
I list  pfsave  zfsave  zcsave 
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0111 

ivol  ach  -bw  cbw  exp  -bw  age  -bw 
00000000 
i . . . _doDlg 

000000000000000000000 

-999 


□ Section  2:  Species  and  Contaminants 

Species/contaminant  data  are  read  by  the  spcs_read( ) function  and  saved  by  the  spcs_save( ) 
function  in  ContamX.  They  are  read  by  ctm_read( ) in  ContamX. 

The  species/ contaminant  section  starts  with: 

_nctm  //  total  number  of  species  simulated  (=  contaminants)  (12) 

The  next  line  lists  the  numbers  of  the  nctm  species  treated  as  contaminants.  The  ordering  of  the 
contaminants  is  important,  and  is  set  in  ContamW. 

ctm[i]  //  i = 0 to  nctm-1 


The  third  line  of  this  section  gives: 

_nspcs  //  the  number  of  species 

This  is  followed  by  a header  line  and  then  two  lines  of  data  for  each  species: 


The  first  line  of  species  data  consists  of: 

nr 

// 

species  number  (12),  in  order  from  1 to 

nspcs 

sf  lag 

// 

1 = simulated,  0 = unsimulated  species 

(12) 

{w} 

ntf lag 

// 

1 = non-trace,  0 = trace  species  (12)  {w} 

molwt 

// 

molecular  weight  - gas  (R4) 

mdiam 

// 

mean  diameter  - particle  [m]  (R4) 

edens 

// 

effective  densiity  - particle  [kg/mA3] 

( R4 ) 

decay 

// 

decay  constant  [1/s]  (R4)  {w} 

ccdef 

// 

default  concentration  [kg/kg  air]  (R4) 

Cp 

// 

(unused)  specific  heat  at  constant  pressure 

[J/kgK] 

ucc 

// 

units  to  display  concentration  (12)  {w} 

name  [] 

// 

species  name  (11) 

(R4) 


The  second  line  is: 

desc []  //  species  description  (II)  {w} 


The  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data  (12) 

Example: 

2 ! contaminants: 

1 2 

4 ! species: 


! # 

s 

t 

molwt 

mdiam 

edens 

decay 

CCdef 

Cp 

u . 

. 

. 

name 

1 

1 

0 

44 . 0000 

0 . 000e+000 

0 . 000e  + 000 

0 . 000e  + 000 

5 . 3184e-004 

1000 . 000 

1 

0 

0 

Cl 

2 

1 

0 

44 . 0000 

0 . 000e+000 

0 . 000e  + 000 

0 . 000e+000 

6 . 8379e-004 

1000 . 000 

1 

0 

0 

C2 

3 

0 

1 

28 . 9645 

0 . 000e+000 

0 . 000e  + 000 

0 . 000e+000 

1 . 0000e+000 

0 . 000 

0 

0 

0 

DryAir 

Dry 

4 

Air 

0 1 

18 . 0153 

0 . 0000e+000 

0 . 0000e  + 000  0 . 0000e  + 000  5.0000e- 

003  0 . 

000 

0 

0 0 H20 

Water  Vapor 
-999 
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□ Section  3:  Level  and  Icon  Data 

The  data  for  recreating  the  SketchPad  is  stored  in  this  section.  The  data  are  read  by  the 
level_read( ) function  and  saved  by  the  level_save( ) function.  The  level  data  are  stored  in 
LEV  DATA  structures  that  are  defined  in  contain. h for  Contain W and  simdat.h  for  ContamX. 

The  icon  data  are  stored  in  ICON_DAT  structures  in  ContamX  and  are  not  saved  in  ContamX. 

The  level/icons  section  starts  with: 

nlev  //  number  of  levels  (12) 


This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nlev  levels. 
Each  level  has  a data  line  that  includes: 


nr 

// 

level  number  (12) , 

in  order  from 

1 to 

nlev 

ref  ht 

// 

reference  elevation 

. of  level 

[m] 

(R4) 

delht 

// 

delta  elevation  to 

next  level 

[m] 

(R4 ) 

{w} 

nicon 

// 

number  of  icons  on 

this  level 

(12 

) 

u rf ht 

// 

units  of  reference 

elevation 

(12) 

{W} 

u dlht 

// 

units  of  delta  elevation  (12) 

{W} 

name  [] 

// 

level  name  (11) 

This  line  is  followed  by  a comment  line  and  then  data  for  nicon  icons. 
Each  icon  has  a data  line  consisting  of: 


icon 

// 

icon  type  - see 

'special  symbols' 

in  contam.h  (12 

row 

// 

row  position  on 

the  SketchPad  (12) 

{w} 

col 

// 

column  position 

on  the  SketchPad  ( 

12)  {W} 

nr 

// 

zone,  path,  duct,  etc.,  number  (12 

) {w} 

The  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data  (12) 


Example: 


2 ! levels  plus  icon  data: 


! # 

ref  Ht 

delHt 

1 

0 . 

000 

3 . 000 

! icn 

col 

row 

# 

14 

15 

17 

0 

23 

19 

17 

5 

23 

21 

17 

6 

23 

23 

17 

7 

23 

25 

17 

8 

23 

27 

17 

9 

16 

49 

33 

0 

42 

19 

34 

6 

2 

3 . 

000 

3 . 000 

1 icn 

col 

row 

# 

162 

10 

14 

1 

145 

11 

14 

0 

185 

32 

38 

7 

185 

-999 

33 

38 

8 

ni  u name 
44  0 0 one 


78  0 0 < 3 > 
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□ Section  4:  Day  Schedules 

Day  schedule  data  are  read  by  the  dschd_read( ) function  and  saved  by  the  dschd_save( ) 
function.  The  data  are  stored  in  the  DY_SCHD  structures  that  are  defined  in  contam.h  for 
ContamW  and  simdat.h  for  ContamX. 

The  day  schedules  section  starts  with: 

_ndsch  //  number  of  day  schedules  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  ndsch  schedules. 

For  each  schedule  the  first  data  line  includes: 

nr  //  schedule  number  (12) ; in  order  from  1 to  _ndsch 

npts  //  number  of  data  points  (12) 

shape  //  0 = rectangular;  1 = trapezoidal  (12) 

utyp  //  type  of  units  (12)  { W } 

ucnv  //  units  conversion  (12)  {w} 

name []  //  schedule  name  (II)  {w} 

and  the  second  line  has: 

desc []  //  schedule  description  (II)  { W } may  be  blank 

This  is  followed  by  a line  for  each  of  the  npts  data  points: 
time  //  time-of-day  [s]  (hh.-mm:ss  converted  to  14) 

Ctrl  //  corresponding  control  value  (R4)  [-] 

The  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

1 ! day- schedules : 

! # npts  shap  utyp  ucnv  name 
12010  DySchdl 
Always  On 
00:00:00  1 
24:00:00  1 
-999 

□ Section  5:  Week  Schedules 

Week  schedule  data  are  read  by  the  wschd_read(  ) function  and  saved  by  the  wschd_save( ) 
function.  The  data  are  stored  in  the  WK  SCHD  structures  that  are  defined  in  contam.h  for 
ContamW  and  simdat.h  for  ContamX. 

The  week  schedules  section  starts  with: 

_nwsch  //  number  of  week  schedules  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nwsch  schedules. 

For  each  week  schedule  the  first  data  line  includes: 

nr  //  schedule  number  (12) ; in  order  from  1 to  _nwsch 

utyp  //  type  of  units  (12)  { W } 

ucnv  //  units  conversion  (12)  { W } 

name []  //  schedule  name  (II)  {w} 

and  the  second  line  has: 

desc []  //  schedule  description  (II)  {w}  may  be  blank 
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and  the  third  line  has: 

jl  ...  jl2  //  12  day  schedule  indices  (12)  - converted  to  pointers 

The  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

1 ! week- schedules : 

! # utyp  ucnv  name 

110  WkSchdl 
Week  schedule . 

111111111111 

-999 

□ Section  6:  Wind  Pressure  Profiles 

Week  pressure  profile  data  are  read  by  the  wind_read( ) function  and  saved  by  the  wind_save( ) 
function.  The  data  are  stored  in  the  WIND  PF  structures  that  are  defined  in  contain. h for 
ContamW  and  simdat.h  for  ContainX. 

The  wind  pressure  profiles  section  starts  with: 

_nwpf  //  number  of  wind  pressure  profiles  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  jvwpf  profiles. 

For  each  wind  pressure  profile  the  first  data  line  includes: 

nr  //  profile  number  (12) ; in  order  from  1 to  _nwpf 

npts  //  number  of  data  points  (12) 

type  //  1 = linear;  2 = cubic  spline;  3 = trigonometric  (12) 

name []  //  schedule  name  (II)  {w} 

and  the  second  line  has: 

desc []  //  profile  description  (II)  { W } may  be  blank 

This  is  followed  by  a line  for  each  of  the  npts  data  points: 

azm[]  //  wind  azimuth  value  {R4}  [degrees] 

coef []  //  normalized  wind  pressure  coefficients  {R4}  [-] 

The  data  points  are  used  to  compute  the  cubic  spline  or  trigonometric  coefficients. 

The  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

2 ! wind  pressure  profiles: 

151  WindProfl 

Wind  pressure  profile  one. 

0.0  1 . 000 

90.0  0.500 

180.0  1.000 

270.0  0.500 

360.0  1.000 
291  WindProf2 

Wind  pressure  profile  two. 

0.0  1.000 

45.0  0.800 
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90 . 0 

0 .200 

135 . 0 

0 .800 

180 . 0 

1 . 000 

225 . 0 

0 . 800 

270 . 0 

0 .200 

315 . 0 

0 .800 

360 . 0 

1 . 000 

999 

□ Section  7:  Kinetic  Reactions 

Kinetic  reaction  data  are  read  by  the  kinetic_read( ) function  and  saved  by  the  kinetic_save( ) 
function.  The  data  are  stored  in  the  KNR  DSC  structures  that  are  defined  in  contain. h for 
ContamW  and  simdat.h  for  ContamX. 

The  kinetic  reactions  section  starts  with: 

_nkinr  //  number  of  kinetic  reactions  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nkinr  reactions. 

For  each  reaction  the  first  data  line  includes  : 

nr  //  reaction  number  (12) ; in  order  from  1 to  _nkinr 

nkrd  //  number  of  reactions  (12) 

name []  //  reaction  name  (II)  {w} 

and  the  second  line  has: 

desc []  //  reaction  description  (II)  {w}  may  be  blank 

This  is  followed  by  nkrd  lines  of  reaction  data: 

prod[]  //  product  species  name  (II) 

src  []  //  source  species  name  (II) 

coef  //  reaction  coefficient  (R4) 

The  kinetic  reactions  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

1 1 kinetic  reactions: 

1 2 Kinrl 

Kinetic  reaction  one. 

Cl  Cl  0.5 
C2  C2  0.5 
-999 

□ Section  8:  Filters 

Filter  data  are  read  by  the  filter_read( ) function  and  saved  by  the  filter_save( ) function.  The 
data  are  stored  in  the  FLT  DSC  structures  that  are  defined  in  contam.h  for  ContamW  and 
simdat.h  for  ContamX. 

The  filter  section  starts  with: 

_nfilt  //  number  of  filters  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  _nfilt  filters. 

For  each  reaction  the  first  data  line  includes: 
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nr  //  filter  number  (12) ; in  order  from  1 to  _nfilt 

nspcs  //  number  of  species  (12) 

name []  //  filter  name  (II)  {w} 

iiml  the  second  line  has: 

desc  []  //  filter  description  (II)  { W } may  be  blank 

This  is  followed  by  nspcs  lines  of filter  efficiency  data: 
spcs  []  //  species  name  (II) 

eff  „ //  filter  efficiency  (R4) 

l he  filter  section  is  terminated  with: 

•99  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

. 1 filters: 

1 2 Fit 1 

21  0.1 
22  0.2 
',99 

j Section  9:  Source/Sink  Elements 

Source/sink  elements  are  read  by  the  cselmt_read( ) function  and  saved  by  the  cselmt_save( ) 
function.  The  data  are  stored  in  the  CSE_DAT  structures  that  are  defined  in  contain. h for 
ContamW  and  simdat.h  for  ContamX.  CSE  DAT  includes  a pointer  to  the  element  specific  data 
structure. 

The  source/sink  elements  section  starts  with: 

_ncse  //  number  of  source/sink  elements 

Th  is  is  followed  by  a data  header  comment  line  and  then  data  for  all  ncse  elements. 

For  each  element  the  first  data  line  includes: 

nr  //  element  number  (12) ; in  order  from  1 to  _ncse 

spcs  []  //  species  name  (II) 

ctype  //  element  data  type  (string  — 12) 

element  type  names  are  stored  in  _cse_dnames  in  ctype 

order . 

name  []  //  element  name  (II)  {w} 

and  the  second  line  has: 

desc  []  //  element  description  (II)  {w}  may  be  blank 

This  is  followed  by  one  or  more  lines  of  data  that  depend  on  the  element  data  type. 

The  introductory  lines  that  follow  give  the  type  number , the  program  macro  defined  as  that 
number,  the  type  name  from  _cse  dnames,  and  the  data  structures  to  hold  the  data.  The  data 
structures  are  defined  in  celmts.h  in  ContamW  and  selmts.h  in  ContamX.  Type  numbers  can 
change  as  long  as  the  ordering  in  esse  names  and  related  arrays  reflect  that  order. 

Element  type  0 [CS  CCF]  ”ccf'  stored  in  structure  CSE  CCF. 

The  constant  coefficient  source  model  data  of: 
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G //  generation  rate  [kg/s]  (R4) 

D //  deposition  rate  [kg/s]  (R4) 

u_G  //  units  of  generation  (12)  {w} 

u_D  //  units  of  deposition  (12)  {w} 

Element  type  1 [CSPRS]  "prs"  stored  in  structure  CSEPRS. 

The  pressure  driven  source  data  of: 

G //  generation  rate  [kg/s]  (R4) 

x //  pressure  exponent  [-]  (R4) 

u_G  //  units  of  generation  (12)  { W } 

Element  type  2 [CS  CUT]  " cut " stored  in  structure  CSE  CUT. 

The  concentration  cutoff  model  data  of  : 


G 

// 

generation  rate  [kg/s] 

(R4 ) 

Co 

// 

cutof  f 

concentration  [kg/kg] 

(R4 

u_G 

// 

units 

of  generation  [12] 

' {«} 

u_C 

// 

units 

of  concentration 

(12) 

{W} 

Element  type  3 [ CS  EDS ] "eds"  stored  in  structure  CSEEDS. 
The  exponential  decay  model  data  of: 


GO 

// 

initial  generation 

rate 

[kg/s] 

k 

// 

decay  constant  [1/s 

] (R4 

) 

u_G 

// 

units  of  generation 

(12) 

<W} 

u_k 

// 

units  of  time  (12) 

{W} 

Element  type  4 [CS  BLS]  "blsn  stored  in  structure  CSEBLS. 

The  boundary  layer  diffusion  model  data  of: 

hm;  //  average  film  mass  transfer  coefficient  [m/s]  (R4) 

rho;  //  film  density  of  air  [kg/m^3]  (R4) 

Kp;  //  partition  coefficient  (R4) 

M;  //  adsorbent  mass/unit  area  [kg/m^2]  (R4) 

u_h ; //  units  of  hm  (12)  {w} 

u_r;  //  units  of  rho  (12)  { W } 

u_M ; //  units  of  M (12)  { W } 

Element  type  5 [CS  BRS]  "brs"  stored  in  structure  CSE  BRS. 

The  burst  source  data  of: 

M //  mass  added  to  zone  in  one  time  step  [kg]  (R4) 

u_M  //  units  of  mass  (12)  { W } 

The  source/sink  element  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

6 1 source/sink  elements: 

1 Cl  ccf  si 
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Constant  Coefficient 
110  0 

2 Cl  prs  s2 
Pressure  driven 

2  2 0 

3 Cl  cut  s3 

Cut-off  Concentration 

3 3 0 0 

4 Cl  eds  s4 
Decaying  Source 

4 4 0 0 

5 Cl  bis  s5 

Boundary  Layer  Diffusion 

5 5 5 5 0 0 0 

6 C2  brs  s6 
Burst 

6 0 
-999 

□ Section  10:  Airflow  Elements 

Airflow  elements  are  read  by  the  afelmt_read( ) function  and  saved  by  the  afelmt_save( ) 
function.  The  data  are  stored  in  the  AFE  DAT  structures  that  are  defined  in  contam.h  for 
ContamW  and  simdat.h  for  ContamX.  AFE  DAT  includes  a pointer  to  the  element  specific  data 
structure. 

The  airflow  elements  section  starts  with: 

_nafe  //  number  of  airflow  elements 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nafe  elements. 

For  each  element  the  first  data  line  includes: 

nr  //  element  number  (12) ; in  order  from  1 to  _nafe 

icon  //  icon  used  to  represent  flow  path  (R4)  {w} 

dtype  //  element  data  type  (string  — 12) 

//  element  type  names  are  stored  in  _afe_dnames  in  dtype  order, 
name []  //  element  name  (II)  {w} 

and  the  second  line  has: 

desc  []  //  element  description  (II)  {w}  may  be  blank 

This  is  followed  by  one  or  more  lines  of  data  that  depend  on  the  element  data  type. 

The  introductory  lines  that  follow  give  the  type  number,  the  program  macro  defined  as  that 
number,  the  type  name  from  afednames,  and  the  data  structures  to  hold  the  data.  The  data 
structures  are  defined  in  celmts.h  in  ContamW  and  selmts.h  in  ContamX.  Type  numbers  can 
change  as  long  as  the  ordering  in  afe  dnames  and  related  arrays  reflect  that  order. 


Element  type  0 [PLORFC]  "plr  orfc"  stored  in  structure  PLRORF. 

The  orifice  data  consist  of: 

lam  //  laminar  flow  coefficient  (R4) 

turb  //  turbulent  flow  coefficient  (R4) 

expt  //  pressure  exponent  (R4) 
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area 

// 

actual  area  [mA2] 

(R4 ) {X} 

dia 

// 

hydraulic  diameter 

[m]  ( R4 ) 

{X} 

coef 

// 

flow  coefficient  ( 

R4 ) {X} 

Re 

// 

laminar/turbulet  transition 

Reynolds  number  [-] (R4)  { X } 

u_A 

// 

units  of  area  (12) 

{x} 

U_D 

// 

units  of  diameter 

(12)  {X} 

/. lenient  type  1 [PLLEAK1  ] "plrleakl"  stored  in  structure  PLR  LEAK. 
Element  type  2 [PLLEAK2]  "plr_leak2”  stored  in  structure  PER  LEAK. 


Element  type  3 [PL  LEAK3]  "plrjeak3n  stored  in  structure  PLR  LEAK. 


I he  leakage  area  data  consist  of: 


lam 

// 

laminar  flow  coefficient  (R4) 

turb 

// 

turbulent  flow  coefficient  (R4) 

expt 

// 

pressure  exponent 

(R4 ) 

coef 

// 

flow  coefficient 

(R4 ) 

{w) 

pres 

// 

reference  pressure  drop  [Pa] 

( R4 ) 

{w} 

areal 

// 

leakage  area  per 

item 

[m"2]  ( 

R4  ) 

{w} 

area2 

// 

leakage  area  per 

unit 

length 

[m"2 / m] 

area3 

// 

leakage  area  per 

unit 

area  [m 

"2  /m 

"2] 

u_Al 

// 

units  of  areal  [m 

*2]  ( 

12)  {W} 

u_A2 

// 

units  of  area2  [m 

^2/m] 

(12)  {W} 

u_A3 

// 

units  of  area3  [m 

"2/m" 

2]  (12) 

{w} 

u dP 

// 

units  of  pressure 

(12) 

{»} 

( R4  ) 
( R4 ) 


{W} 

{W} 


Element  type  4 [PL  CONN]  "p/r  conn"  stored  in  structure  PLR  CONN. 
The  (A  SC  OS  compatible)  connection  data  consist  of: 


lam 

// 

laminar  flow  coefficient  (R4) 

turb 

// 

turbulent  flow  coefficient  (R4 

expt 

// 

pressure  exponent 

- 0.5  (R4 ) 

area 

// 

actual  area  [m"2] 

(R4 ) {W} 

coef 

// 

flow  coefficient 

(R4 ) {W} 

u_A 

// 

units  of  area  (12) 

' {w} 

Element  type  5 [PL  QCN]  "plr  cjcn"  stored  in  structure  PLR  QCN. 

The  volume  flow  power/aw  data  consist  of: 

lam  //  laminar  flow  coefficient  (R4) 

turb  //  turbulent  flow  coefficient  (R4) 

expt  //  pressure  exponent  (R4) 

Element  type  6 [PL  FCN]  "plr  J~cn”  stored  in  structure  PLR  FCN. 
The  mass  flow  powerlaw  data  consist  of: 

lam  //  laminar  flow  coefficient  (R4) 

turb  //  turbulent  flow  coefficient  (R4) 

expt  //  pressure  exponent  (R4) 
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Element  type  7 [PL  TEST  1 ] "pin Jest  1 " stored  in  structure  PLRTEST1 . 

The  single  test  point  powerlaw  data  consist  of: 

lam  //  laminar  flow  coefficient  (R4) 

turb  //  turbulent  flow  coefficient  (R4) 

expt  //  pressure  exponent  (R4) 

dP  //  pressure  drop  [Pa]  (R4)  {w} 

Flow  //  flow  rate  [kg/s]  (R4)  {w} 

u_P  //  units  of  pressure  drop  {w} 

u_F  //  units  of  flow  (12)  {w} 

Element  type  8 [PLJTEST2]  "plr  test2" stored  in  structure  PLRTEST2. 

The  two  test  points  power  law  data  consist  of: 


lam 

// 

laminar  flow  coefficient  ( 

R4 ) 

turb 

// 

turbulent  flow  coefficient 

(R4 ) 

expt 

// 

pressure  exponent  (R4) 

dPl 

// 

point 

1 pressure  drop  [Pa] 

(R4 ) 

{w} 

FI 

// 

point 

1 flow  rate  [kg/s]  ( 

R4 ) {W} 

dP2 

// 

point 

2 pressure  drop  [Pa] 

(R4 ) 

{w} 

F2 

// 

point 

2 flow  rate  [kg/s]  ( 

R4 ) {W} 

\ — 1 
ft 

1 

d 

// 

units 

of  pressure  drop  (12 

) {w} 

u_Fl 

// 

units 

of  flow  (12)  { W } 

u_P2 

// 

units 

of  pressure  drop  (12 

) {w} 

u_F2 

// 

units 

of  flow  (12)  {w} 

Element  type  ()  [PLCRACK]  "plr crack"  stored  in  structure  PLRCRACK. 
The  crack  power! aw  data  consist  of: 


lam 

// 

laminar  flow  coefficient  (R4) 

turb 

// 

turbulent  flow  coefficient  (R4 

expt 

// 

pressure  exponent  (R4) 

length 

// 

crack  length  [m]  (R4 

) {w} 

width 

// 

crack  width  [m]  (R4) 

{w} 

u L 

// 

units  of  length  (12) 

{w} 

u W 

// 

units  of  width  (12) 

{w} 

Element  type  10  [ PL  STAIR ] "plr  stair"  stored  in  structure  PLR  STAIR. 
The  stairwell  power l aw  data  consist  of: 


lam 

// 

laminar 

flow  coefficient  (R4) 

turb 

// 

turbulent  flow  coefficient  (R4) 

expt 

// 

pressure 

exponent 

(R4 ) 

Ht 

// 

distance 

between 

levels  [m]  (R4) 

{w} 

Area 

// 

cross-sectional  area  [rrh2]  (R4) 

{w} 

peo 

// 

density 

of  people 

[pers/mA2]  (R4 

) {w} 

tread 

// 

1 = open 

tread  0 

= closed  { W } 

u_A 

// 

units  of 

area  (12 

) {w} 

U_D 

// 

units  of 

distance 

(12)  { W} 

Element  type  11  [PL  SHAFT]  "plr  shaft"  stored  in  structure  PLRJSHAFT. 
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The  shaft  power  law  data  consist  of: 


lam 

// 

laminar  flow  coefficient  (R4 

) 

turb 

// 

turbulent  flow  coefficient  ( 

R4  ) 

expt 

// 

pressure  exponent 

(R4 ) 

Ht 

// 

distance  between  levels 

[m] 

( R4 

Area 

// 

cross-sectional  area  [m 

"2]  ( 

R4  ) 

Perim 

// 

perimeter  [m]  (R4) 

{w} 

rough 

// 

roughness  [m]  (R4) 

{w} 

u_A 

// 

units  of  area  (12) 

{w} 

U_D 

// 

units  of  distance 

(12) 

{W} 

u_P 

// 

units  of  perimeter 

(12) 

{W} 

u_R 

// 

units  of  roughness 

(12) 

{W} 

Element  type  12  [PLBDQ]  "plrbdq" stored  in  structure  PER  BDQ. 
The  volume  flow  powerlaw  backdraft  damper  data  consist  of: 

lam  //  laminar  flow  coefficient  {R4} 

Cp  //  turbulent  flow  coefficient  ( dP  > 0 ) {R4} 

xp  //  pressure  exponent  ( dP  > 0 ) {R4} 

Cn  //  turbulent  flow  coefficient  ( dP  < 0 ) {R4} 

xn  //  pressure  exponent  ( dP  < 0 ) {R4} 

Element  type  13  [PL  BDF]  "plrbdf'  stored  in  structure  PER  BDF. 
The  mass  flow  powerlcnv  backdraft  damper  data  consist  of: 


lam 

// 

laminar  flow  coefficient  {R4} 

Cp 

// 

turbulent  flow  coefficient  ( 

dP  > 

0 

xp 

// 

pressure  exponent  ( dP  > 0 ) 

{ R4 } 

Cn 

// 

turbulent  flow  coefficient  ( 

dP  < 

0 

xn 

// 

pressure  exponent  ( dP  < 0 ) 

{R4} 

Element  type  14  [QFRjQAB]  "qfrqab"  stored  in  structure  QFRQAB. 

The  volume  flow  quadratic  data  consist  of: 

a //  dP  = a*Q  + b*Q*Q  {R4} 

b //  { R4 } 

Element  type  15  [QFR  QAF]  "qfr  Jab" stored  in  structure  QFRFAB. 

The  mass  flow  quadratic  data  consist  of: 

a //  dP  = a*F  + b*  F*  F {R4} 

b //  { R4 } 

Element  type  16  [QFR  CRACK]  "qfr  crack" stored  in  structure  QFR  CRACK. 
The  crack  mass  flow  quadratic  data  consist  o f: 


a 

// 

dP  = a*  F + b*F*F  {R4} 

b 

// 

{R4} 

length 

// 

crack  length  [m]  {R4} 

width 

// 

crack  width  [m]  {R4} 

depth 

// 

crack  depth  [m]  {R4} 
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nB 

// 

number  of 

bends 

u 

_L 

// 

units  of 

length 

u 

_W 

// 

units  of 

width 

u 

_E> 

// 

units  of 

depth 

Element  type  1 7 [QFRTEST2]  "qfr_test2"  stored  in  structure  QFR  TEST2. 
The  two  test  points  mass  flow  quadratic  data  consist  of: 


a 

// 

dP  = , 

a*F  + b*F*F 

{ R4 } 

b 

// 

{R4 } 

dPl 

// 

point 

1 pressure 

drop  [Pa]  ( 

R4 ) 

{w} 

FI 

// 

point 

1 flow  rate 

[kg/s]  ( R4 

> {w} 

dP2 

// 

point 

2 pressure 

drop  [Pa]  ( 

R4  ) 

{w} 

F2 

// 

point 

2 flow  rate 

[kg/s]  (R4 

) {w} 

U_P1 

// 

units 

of  pressure 

drop  (12) 

{w) 

u_Fl 

// 

units 

of  flow  (12 

) {w} 

u_P2 

// 

units 

of  pressure 

drop  (12) 

{w} 

u_F2 

// 

units 

of  flow  (12 

) {w} 

Element  type  18  [DR  DOORJ  "dor  door”  stored  in  structure  AFE  DOR. 


The  single  opening  doorway  data  consist  of: 


lam 

// 

laminar  flow  coefficient  ( 

R4 ) 

turb 

// 

turbulent  flow  coefficient 

(R4 ) 

expt 

// 

pressure  exponent  (R4) 

dTmin 

// 

minimum  temperature  difference  for  two-way  flow 

ht 

// 

height  of  doorway  [m]  (R4) 

wd 

// 

width  of  doorway  [m]  (R4) 

cd 

// 

discharge  coefficient 

u T 

// 

units  of  temperature  (12) 

{w} 

U_H 

// 

units  of  height  (12)  { W } 

u_W 

// 

units  of  width  (12)  {w} 

[c] 


(R4) 


Element  type  19  [DR  PL2]  " dor _pl2  " stored  in  structure  DRPL2. 
The  double  opening  doorway  data  consist  of: 


lam 

// 

laminar  flow  coefficient  ( 

R4 ) 

turb 

// 

turbulent  flow  coefficient 

( R4 ) 

expt 

// 

pressure  exponent  (R4) 

dH 

// 

distance  above  | below  midpoint  [m]  {R4} 

ht 

// 

height  of  doorway  [m]  (R4) 

{ W in  v . 2.0} 

wd 

// 

width  of  doorway  [m]  (R4) 

{w} 

cd 

// 

discharge  coefficient  [-] 

(R4)  { W> 

u_H 

// 

units  of  height  (12)  {w} 

u W 

// 

units  of  width  (12)  {w} 

Element  type  20  [FN  CMF]  'fan  cmf  stored  in  structure  AFEjCMF. 

The  constant  mass  flow  fan  data  consist  of: 

Flow  //  design  flow  rate  [kg/s]  (R4) 

u_F  //  units  of  flow  (12)  { W } 
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Element  type  21  [FNjCVF]  "fan  cvj"  stored  in  structure  AFEjOVF. 

The  constant  volume  flow  fan  data  consist  of: 

Flow  //  design  flow  rate  [m^3/s]  (R4) 

u_F  //  units  of  flow  (12)  {w} 


Element  type  22  [ FN  FANJ  'fan  fan"  stored  in  structure  AFE  FAN. 


The  first  line  of  performance  curve  fan  data  consists  of: 

laminar  flow  coefficient  (R4) 
turbulent  flow  coefficient  (R4) 
pressure  exponent  (R4) 

reference  fluid  density  [kg/m^3]  {R4} 

free  delivery  flow  (prise  = 0)  [kg/s]  {R4} 
shut-off  pressure  (flow  = 0)  [Pa]  {R4} 
fan  is  off  if  (RPM/rated  RPM)  < off  {R4} 


lam 

// 

turb 

// 

expt 

// 

rdens 

// 

fdf 

// 

sop 

// 

off 

// 

The  second  line  consists  of: 


fpc  [4] 
npt  s 
Sarea 
u_Sa 

The  next 
mF 

u_mF 

dP 

u_dP 

rP 

u rP 


//  fan  performance  polynomial  coefficients 
//  number  of  mesaured  data  points  (12)  { W } 

//  shut-off  orifice  area  [m^2]  { R4 } { W } 

//  units  of  shut-off  area  (12)  {w} 

npts  lines  consists  of : 

//  measured  flow  rates  [kg/s]  (R4)  { W } 

//  units  of  measured  flows  (12)  {w} 

//  measured  pressure  rises  [Pa]  (R4)  {w} 

//  units  of  pressure  rises  (12)  {w} 

//  revised  pressure  rises  [Pa]  (R4)  { W } 

//  units  of  revised  pressures  (12)  { W } 


{R4} 


The  airflow  element  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 


Example: 

24  ! flow | duct  elements: 

1 24  dor_door  DR_DOOR 

DR_DOOR  Single  opening  w/  2 -way  flow 
0.0741669  1.76494  0.5  0.01  2 0.8  0.78  000 

2 24  dor_pl2  DR_PL2 
DR_PL2  Two -opening  model 

0.0185417  0.882469  0.5  0.444444  2 0.8  0.78  0 0 

3 30  f an_cmf  FN_CMF 

FN_CMF  Constant  mass  flow  fan  model 
1 0 

4 29  f an_cvf  FN_CVF 

FN_CVF  Constant  volume  flow  fan  model 
1 0 

5 30  f an_f an  FN_FAN 

FN_FAN  Cubic  polynomial  fan  model 
7 . 2e- 006  0.00848528  0.5  1.2041  -0.377789  0.0286444  0.1 
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0.0286444  0.0745766  -0.00327397  5.29862e-005  4 0.01  0 
1 0 0.1  0 0.1  0 
10  0 0.5  0 0.5  0 
30  0 0.75  0 0.75  0 
35  0 0.9  0 0.9  0 

6 25  plr_conn  PLR_CONN 

ASCOS  Connection  element.  Analysis  of  Smoke  Control  of  Systems  ... 
8 . 38053e-008  0.000188562  0.5  0.0002  0.666667  3 

7 23  plr_crack  PLR_CRACK 

Crack  element  using  powerlaw  relationship. 

1 . 84e- 008  0.000861959  0.68394  2 0.002  0 4 

8 23  plr_f cn  PLR_FCN 
Power  law  for  mass  flow. 

3 . 52946e-005  0.01  0.5 

9 23  plr_leakl  PLR_LEAK1 
Leakage  element  (per  item) . 

2 . 4e- 008  8 . 48528e- 005  0.5  0.6  10  0.0001  0 0 2 2 2 0 

10  23  plr_leak2  PLR_LEAK2 
Leakage  element  (per  unit  length) . 

3 . 8063e-009  6.00712e-005  0.65  0.6  10  0 0.0001  02220 

11  23  plr_leak3  PLR_LEAK3 
Leakage  element  (per  unit  area) . 

3 . 8063e-009  6.00712e-005  0.65  0.6  10  0 0 0.0001  2221 

12  23  plr_orf c PLR_ORFC 
Orifice  element. 

2 . 4e-005  0.00848528  0.5  0.01  0.1  0.6  30  0 0 

13  23  plr_qcn  PLR_QCN 
Power  law  for  volume  flow. 

3 . 52946e- 005  0.01  0.5 

14  23  plr_shaf t PLR_SHAFT 
Shaft  powerlaw  model. 

0.306565  30.9005  0.508447  3 6 10  0.1  0000 

15  23  plr_stair  PLR_STAIR 
Stairwell  powerlaw  model. 

0.146333  2.83196  0.5  3 12.5  0100 

16  23  plr_testl  PLR_TEST1 
Single  point  test  data  element . 

2.47343e-005  0.0086575  0.5  4 0.019  0 0 

17  23  plr_test2  PLR_TEST2 
Two  point  test  data  element. 

6 . 35906e-005  0.00913228  0.461488  4 0.019  10  0.029  0000 

18  23  plr_bdf  PL_BDF 

PL_BDF  Backdraft  Damper  based  on  mass  flow  rate 
3 . 52946e-005  0.01  0.5  0.0001  0.5 

19  23  plrjodq  PL_BDQ 

PL_BDQ  Backdraft  Damper  based  on  volume  flow  rate 
3 . 52  946e- 005  0.01  0.5  0.0001  0.5 

20  23  qfr_crack  QF_CRACK 

This  description  is  the  maximum  allowable  length  that  CONTAMW  alio 
565.645  90835.5  2 0.002  0.05  2042 

21  23  qfr_fab  QF_FAB 

QF  FAB  Quadratic  mass  flow  model 
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1234.12  123456 

22  23  qfr_qab  QF_QAB 

QF_QAB  Qadratic  volume  flow  model 
1 1234.12 

23  23  qfr_test2  QF_TEST2 

QF_TEST2  Quadratic  test  data  (2  points) 

-44.6461  13430.1  4 0.019  10  0.029  0000 

24  30  fan_cmf  a 

1 0 
-999 

□ Section  11:  Duct  Elements 

Duct  elements  are  read  by  the  afelmt_read( ) function  with  the  duct  flag  set  to  1 and  saved  by  the 
afelmt_save( ) function.  The  data  are  stored  in  the  AFEDAT  structures  that  are  defined  in 
contam.h  for  ContamW  and  simdat.h  for  ContamX.  AFE  DAT  includes  a pointer  to  the  element 
specific  data  structure. 

The  duct  elements  section  starts  with: 

_ndfe  //  number  of  duct  flow  elements 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  _ndfe  elements. 

For  each  element  the  first  data  line  includes: 

nr  //  element  number  (12) ; in  order  from  1 to  _nafe 

icon  //  icon  used  to  represent  flow  path  ((R4)  {w} 

dtype  //  element  data  type  (string  12) 

//  element  type  names  are  stored  in  _afe_dnames  in  dtype  order, 
name []  //  element  name  (II)  { W } 

and  the  second  line  has: 

desc  []  //  element  description  (II)  { W } may  be  blank 

This  is  followed  by  two  or  more  lines  of  data  that  depend  on  the  element  data  Wpe. 

The  introductory  lines  that  follow  give  the  type  number,  the  program  macro  defined  as  that 
number,  the  type  name  from  afednames,  and  the  data  structures  to  hold  the  data.  The  data 
structures  are  defined  in  celmts.h  in  ContamW  and  selmts.h  in  ContamX.  Type  numbers  can 
change  as  long  as  the  ordering  in  afe  dnames  and  related  arrays  reflect  that  order. 


Element  type  23  [DD  DWC]  "dct  dwc”  stored  in  structure  DEF  DWC. 
The  Darcy-Colebrook  data  consist  of: 


hdia 

// 

hydraulic  diameter 

[m]  ( R4 ) 

area 

// 

cross  sectional  area  [mA2]  (R4) 

ed 

// 

relative  roughness 

(rough/hdia)  (R4) 

lam 

// 

laminar  total  loss 

coefficient  per  [m] 

rough 

// 

roughness  dimension 

[m]  ( R4 ) 

u_R 

// 

units  for  roughness 

(12)  {W} 

Element  type  24  [DDPLRJ  "dct _plr”  stored  in  structure  DFEORF. 
The  orifice  data  consist  of: 
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lam 

// 

laminar  flow  coefficient  (R4 

) 

turb 

// 

turbulent  flow  coefficient  ( 

R4  ) 

expt 

// 

pressure  exponent 

(R4 ) 

area 

// 

actual  area  [m^2] 

(R4 ) {X} 

dia 

// 

hydraulic  diameter 

[m]  ( R4 ) 

{x} 

coef 

// 

flow  coefficient  ( 

R4 ) {X} 

Re 

// 

laminar/turbulet  transition 

Reynolds  number  [-] (R4)  { X } 

u_A 

// 

units  of  area  (12) 

{x} 

U_D 

// 

units  of  diameter 

(12)  {X} 

Element  type  26  [DD  QCN]  "dctqcn"  stored  in  structure  DFE  OCN. 

The  volume  flow  powerlaw  data  consist  of: 

lam  //  laminar  flow  coefficient  (R4) 

turb  //  turbulent  flow  coefficient  (R4) 

expt  //  pressure  exponent  (R4) 

Element  type  25  [DD  FCN]  " dct Jen" stored  in  structure  DFE  FCN. 

The  mass  flow  powerlaw  data  consist  of: 

lam  //  laminar  flow  coefficient  (R4) 

turb  //  turbulent  flow  coefficient  (R4) 

expt  //  pressure  exponent  (R4) 

Element  type  28  [DD  CMF]  "dct  cmfi'  stored  in  structure  DFE  CMF. 
The  constant  mass  flow  fan  data  consist  of 

Flow  //  design  flow  rate  [kg/s]  (R4) 

u_F  //  units  of  flow  (12)  { W } 

Element  type  29  [29  CVF]  "detevf  stored  in  structure  DFECVF. 

The  constant  volume  flow  fan  data  consist  of: 

Flow  //  design  flow  rate  [mA3/s]  (R4) 

u_F  //  units  of  flow  (12)  { W } 

Element  type  27  [DD  FAN]  "dct ffan"  stored  in  structure  DFE  FAN. 

The  first  line  of  performance  curve  fan  data  consists  of: 

lam  //  laminar  flow  coefficient  (R4) 

turb  //  turbulent  flow  coefficient  (R4) 

expt  //  pressure  exponent  (R4) 

rdens  //  reference  fluid  density  [kg/m^3]  {R4} 

fdf  //  free  delivery  flow  (prise  = 0)  [kg/s]  {R4} 

sop  //  shut-off  pressure  (flow  = 0)  [Pa]  {R4} 

off  //  fan  is  off  if  (RPM/rated  RPM)  < off  {R4} 

The  second  line  consists  of: 

fpc  [4]  //  fan  performance  polynomial  coefficients  {R4} 

npts  //  number  of  mesaured  data  points  (12)  { W } 
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Sarea  //  shut-off  orifice  area  [m^2]  {R4}  {w} 

u_Sa  //  units  of  shut-off  area  (12)  {w} 

The  next  npts  lines  consists  of: 

mF  //  measured  flow  rates  [kg/s]  (R4)  {w} 

u_mF  //  units  of  measured  flows  (12)  { W } 

dP  //  measured  pressure  rises  [Pa]  (R4)  { W } 

u_dP  //  units  of  pressure  rises  (12)  { W } 

rP  //  revised  pressure  rises  [Pa]  (R4)  {w} 

u_rP  //  units  of  revised  pressures  (12)  { W } 


Element  type  30  [DDBDQ]  "dctbdq"  stored  in  structure  DFE  BDQ. 
The  volume  flow  power  law  backdraft  damper  data  consist  of: 


lam 

// 

laminar  flow  coefficient  { R4 } 

Cp 

// 

turbulent 

flow  coefficient  ( 

dP  > 0 

xp 

// 

pressure 

exponent  ( dP  > 0 ) 

{R4} 

Cn 

// 

turbulent 

flow  coefficient  ( 

dP  < 0 

xn 

// 

pressure 

exponent  ( dP  < 0 ) 

{ R4 } 

Element  type  31  [DD  BDF]  "dctjbdf  stored  in  structure  DFE  BDF. 


The  mass  flow  powerlaw  backdraft  damper  data  consist  of: 

lam  //  laminar  flow  coefficient  {R4} 

Cp  //  turbulent  flow  coefficient  ( dP  > 0 ) {R4} 

xp  //  pressure  exponent  ( dP  > 0 ) { R4 } 

Cn  //  turbulent  flow  coefficient  ( dP  < 0 ) {R4} 

xn  //  pressure  exponent  ( dP  < 0 ) {R4} 


Each  duct  element 


Hdia 

// 

perim 

// 

area 

// 

ma  j or 

// 

minor 

// 

As 

// 

Qr 

// 

Pr 

// 

CL 

// 

Prs 

// 

shape 

// 

u_D 

// 

u_P 

// 

u_A 

// 

u mj 

// 

u mn 

// 

u_Qr 

// 

u Pr 

// 

then  has  the  following  geometry  and  leakage  data  stored  in  structure  DUCT. 

hydraulic  diameter  [m]  {R4} 

perimeter  [m]  {R4} 

cross  sectional  area  [m^2]  {R4} 

major  dimension  of  rectangular  or  oval  duct  [m]  {R4} 

minor  dimension  of  rectangular  or  oval  duct  [m]  {R4} 

duct  segment  surface  area  [mA2]  {R4} 

duct  leakage  rate  at  Pr  [mA3/mA2]  {R4} 

dPstatic  for  leakage  rate  [Pa]  {R4} 

ASHRAE  leakage  class  number  {R4} 
standard  dP  for  leakage  rate  [Pa]  {R4} 

0 = circle,  1 = rectangle,  2 = oval,  3 = other  (12)  {w} 

units  for  diameter  (12)  {w} 

units  for  perimeter  (12)  { W } 
units  for  area  (12)  {w} 

12)  {W} 

12)  {w} 

{w} 

{w} 


units  for  major  dimension 
units  for  minor  dimension 
units  for  leakage  rate  (12 
units  for  standard  dP  (12) 


The  duct  element  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 
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Example: 

• . flow | duct  elements: 

. 13  dct_dwc  Dctl 

. -t  one . 

• -?  - 0 0 5 0 4 

.2  0.628319  0.0314159  0.2  0.2  0 0 250 
4 4 2 4 4 0 0 
. 23  dct_plr  Dct2 

;ct  two 

..  . 4 e - 0 0 5 0.00848528  0.5  0.01  0.1  0.6  0 0 
.2  0.628319  0.0314159  0.2  0.2  0 0 250 
4 4 2 4 4 0 0 
■ 23  dct_fcn  Dct3 
' uct  three . 

3 . 52946e-005  0.01  0.5 
.2  0.628319  0.0314159  0.2  0.2  0 0 250 
34424400 

4 23  dct_qcn  Dct4 
Duct  four 

3 . 52946e- 005  0.01  0.5 

0.2  0.628319  0.0314159  0.2  0.2  0 0 250 
04424400 

5 23  dct_fan  Dct5 
Duct  five 

7 . 2e- 006  0.00848528  0.5  1.2041  4.53711  764.429  0.1 
764.429  -22.0238  28.2143  -13.3333  5 0.01  0 

0 0 765  0 765  0 

1 0 755  0 755  0 

2 0 730  0 730  0 

3 0 590  0 590  0 

4 0 275  0 275  0 

0.2  0.628319  0.0314159  0.2  0.2  0 0 250 
04424400 

6 23  dct_cmf  Dct6 
Duct  6 

1 0 

0.2  0.628319  0.0314159  0.2  0.2  0 0 250 
04424400 

7 23  dct_cvf  Dct7 
Duct  seven 

1 0 

0.2  0.628319  0.0314159  0.2  0.2  0 0 250 
04424400 

8 23  dct_bdq  Dct8 
Duct  eight 

3 . 52946e- 005  0.01  0.5  0.0001  0.5 

0.2  0.628319  0.0314159  0.2  0.2  0 0 250 

04424400 

9 23  dct_bdf  Dct9 
Duct  nine 

3 . 52946e-005  0.01  0.5  0.0001  0.5 

0.2  0.628319  0.0314159  0.2  0.2  0 0 250 
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04424400 

-999 


□ Section  12:  Control  Nodes 

Control  node  data  are  read  by  the  ctrl_read( ) function  and  saved  by  the  ctrl_save(  ) function. 
The  data  are  stored  in  the  CTRL  DSC  structures  that  are  defined  in  contain. h for  ContamW  and 
the  CT  NODE  structures  defined  simdat.h  for  ContamX. 


The  control  nodes  section  starts  with: 

nctrl  / / number  of  control  nodes 


12 


This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nctrl  control  nodes. 

For  each  control  node  the  first  data  line  includes: 

nr  //  node  (SketchPad)  number  (12);  in  order  from  1 to  _nzone 

type  //  node  data  type  (string  — 12) 

Node  type  names  are  stored  in  _ctrl_names  in  type  order, 
seqnr  //  computation  sequence  number  (12);  set  in  ContamW 

flags  //  flags  for  offset  & scale  and  time  constant  (U2) 

nl  //  SketchPad  number  of  input  node  #1  (12) 

n2  //  SketchPad  number  of  input  node  #2  (12) 

name []  //  element  name  (II)  { W } 

and  the  second  line  has: 

desc  []  //  control  node  description  (II)  {w}  may  be  blank 

This  may  be  followed  by  one  more  line  of  data  that  depends  on  the  node  type. 

Node  type  0 [CTSNS]  "sns"  stored  in  structure  SENSOR  {Wf  or  SNSDAT  {X}. 

offset  //  offset  value  (R4) 

scale  //  scale  value  (R4) 

tau  //  time  constant  (R4) 

oldsig  //  signal  at  last  time  step  - for  restart  (R4) 
source  //  index  of  source  (source  not  defined  at  read  time)  (12) 

type  //  type  of  source:  l=zone,  2=path,  3=junction,  4=duct. 

measure  //  0=contaminant , l=temperature , 2=flow  rate,  3=dP  ... 
species  []  //  species  name  [II]  ; convert  to  pointer 

Node  type  1 [ CT  SCH]  "sch" stored  in  structure  SCHDAT. 

ps  //  week  schedule  index  (12) ; converted  to  pointer 

Node  type  2 [CT_SET]  "set"  stored  in  structure  SETDAT . 

value  //  constant  value  (R4) 

Node  type  3 fCT  CVF]  ”cvf' stored  in  structure  CDVDAT.  {Contain  2.1 } 

Name []  //  name  of  the  value  read  from  the  Continuous  Values  file 

Node  type  4 [CT  DVF]  ”dvf' stored  in  structure  CDVDAT.  {Contain  2. 1} 

Name  []  //  name  of  the  value  read  from  the  Discrete  Values  file  (II 

Node  type  5 [CT  LOG]  "log” stored  in  structure  LOGDAT. 

Offset  //  offset  value  (R4) 

Scale  //  scale  value  (R4) 

header  []  //  header  string  (II) 

units  []  //  units  string  (II) 


(12 


(12 


II 
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udef  //  true  if  using  default  units  (12)  {w} 

Node  type  6 [CT  PAS]  "pas"  has  no  additional  data. 

Node  type  7 [CTMOD]  "mod"  stored  in  structure  MOD. 

offset  //  offset  value  (R4) 

scale  //  scale  value  (R4) 

Node  type  8 [CT  HYS]  "hvs" stored  in  structure  HYSDAT. 

slack;  //  hysteresis  parameter  (R4) 
slope  //  1.0  / (1.0  - slack)  (R4) 

oldsig  //  prior  output  signal  (R4) 

Node  type  9 [CT_ABS]  "abs"  has  no  additional  data. 

Node  type  10  [CT  BIN]  "bin"  has  no  additional  data. 

Node  type  11  [ CT  DLS ] "dls" stored  in  structure  C DVD AT.  {Contain  2.1} 

dsincr  //  day  schedule  number  for  increasing  signal  (12) 
dsdecr  //  day  schedule  number  for  decreasing  signal  (12) 

Node  type  12  [CTDLX]  "dlx" stored  in  structure  CDVDAT.  {Contain  2.1 } 

tauincr  //  time  constant  for  increasing  signal  [s]  (14) 

taudecr  //  time  constant  for  decreasing  signal  [s]  (14) 

Node  type  13  [CT  INTJ  "int"  has  no  additional  data. 

Node  type  14  [CTRA  V]  "rav"  stored  in  structure  CDVDAT.  {Contain  2.1} 

tspan  //  time  span  for  the  running  average  [s]  (14) 

Node  type  15  [ CT  IN V]  "inv"  has  no  additional  data. 

Node  type  16  [CT  AND]  "and"  has  no  additional  data. 

Node  type  17  [CTOR]  "od"  has  no  additional  data. 

Node  type  18  [CT  XOR]  "xor"  has  no  additional  data. 

Node  type  19  [CT  ADD]  "add"  has  no  additional  data. 

Node  type  20  [CTSUB]  "sub"  has  no  additional  data. 

Node  type  21  [CTMUL]  "mill"  has  no  additional  data. 

Node  type  22  [CTDIV]  " div " has  no  additional  data. 

Node  type  23  [ CT  SUM]  "sum" stored  in  structure  SUMDAT. 

Node  type  24  [CT_A  VG]  "avg" stored  in  structure  SUMDAT. 

Node  type  25  [CT  MAX]  "max" stored  in  structure  SUMDAT. 

Node  type  26  [CT  MIN]  "min" stored  in  structure  SUMDAT. 

nval  //  number  of  values  to  be  processed  (12) 

pc  . . . //  indices  of  nval  control  nodes  (12) 

Node  type  27  [CT  LLSJ  "l Is"  has  no  additional  data. 

Node  type  28  [CT JJLS]  "ids"  has  no  additional  data. 

Node  type  29  [CTSUM]  "sum"  stored  in  structure  BAN  DAT. 
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\ode  type  30  [CT_A  VG]  "avg"  stored  in  structure  BAN  DAT. 

: »:id  //  width  of  bans  (R4) 

\ode  type  31  [CTLLC]  "lie”  has  no  additional  data. 

\ode  type  32  [CT_ULC]  "ulc"  has  no  additional  data. 

\<>de  type  33  [CTPC1]  "pel”  stored  in  structure  PC  DAT. 

//  proportional  gain  factor  (R4) 

\ode  type  34  [CTPIC]  "pic"  stored  in  structure  PIC  DAT. 

: //  proportional  gain  factor  (R4) 

; //  integral  gain  factor  (R4) 

Idsig  //  prior  output  signal  - for  restart  (R4) 

Lderr  //  prior  error  value  - for  restart  (R4) 

The  control  nodes  section  is  terminated  with: 

*99  //  used  to  check  for  a read  error  in  the  above  data 


Example: 

3 1 control  nodes : 

# typ  seq  f n cl 

1 sns  100  0 

zone  sensor 

0100110  Cl 

2 sns  200  0 

zone  sensor 

0100110  C2 

3 log  501  2 

report 

Oil  MassFraction 

4 log  601  1 

report 

Oil  MassFraction 

5 sns  300  0 

path  sensor 

0100322  none 

6 sns  400  0 

path  sensor 

0100422  none 

7 log  701  5 

report 

Oil  FlowRate  kg/s 

8 log  801  6 

report 

Oil  FlowRate  kg/s 

-999 


c2  s#  data 
0 <none> 

0 <none> 

0 Z5C2 

kg/kg 
0 Z5C1 

kg/kg 

0 <none> 

0 <none> 

0 Path-L 

0 Path-R 


j Section  13:  Simple  Air  Handling  System  (AHS) 

AHS  data  are  read  by  the  system_read( ) function  and  saved  by  the  system_save( ) function.  The 
data  are  stored  in  the  AHS_DSC  structures  that  are  defined  in  contain. h for  ContamW  and 
simdat.h  for  ContamX. 
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The  AHS  section  starts  with: 

_nahs  //  number  of  AHS  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nahs  systems. 

For  each  AHS  the  first  data  line  includes: 

nr  //  AHS  number  (12) ; in  order  from  1 to  _nahs 

zone_r  //  return  zone  number  (12) 

zone_s  //  supply  zone  number  (12) 

path_r  //  recircultaion  air  path  number  (12) 

path_s  //  outdoor  air  path  number  (12) 

path_x  //  exhaust  path  number  (12) 

and  the  second  line  has: 

desc []  //  AHS  description  (II)  { W } may  be  blank 

The  AHS  section  is  terminated  with: 

-999  II  used  to  check  for  a read  error  in  the  above  data 

Example: 

1 ! simple  AHS : 

! # zr#  zs#  pr#  ps#  px#  name 
1 2 3 29  30  31  Ahsl 

Simple  Air  Handling  System  #1 
-999 


□ Section  14:  Zones 

Zone  data  are  read  by  the  zone_read( ) function  and  saved  by  the  zone_save( ) function.  The 
data  are  stored  in  the  ZONE  DSC  structures  that  are  defined  in  contain. h for  Contain W and 
simdat.h  for  ContamX. 


The  zone  section  starts  with: 

nzone  / / number  of  zones 


12) 


This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nzone  zones. 

For  each  zone  the  data  line  includes: 

zone  number  (12) ; in  order  from  1 to  _nzone 
zone  flags  - bits  defined  in  contam.h  (U2) 
week  schedule  index  (12) ; converted  to  pointer 
control  node  index  (12);  converted  to  pointer 
kinetic  reaction  index  (12);  converted  to  pointer 
building  level  index  (12) ; converted  to  pointer 
zone  height  [m]  (R4) 

zone  volume  [mA3]  (R4) 

initial  zone  temperature  [K]  (R4) 

initial  zone  pressure  [Pa]  (R4) 
zone  name  (II)  { W } 
units  of  height  (12)  {w} 

units  of  volume  (12)  {w} 

units  of  temperature  (12)  { W } 

units  of  pressure  (12)  {w} 


nr 

II 

flags 

II 

ps 

II  ■ 

pc 

II 

pk 

II  : 

Pi 

II  ■ 

relHt 

II 

Vol 

II 

TO 

II 

P0 

II 

name  [] 

II 

u Ht 

//  ' 

u_V 

//  ' 

u T 

//  ' 

u_P 

//  ' 

The  zones  section  is 
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-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

7 ! zones : 


z# 

f 

s# 

c# 

k# 

1# 

relHt 

Vol 

TO 

P0 

name 

u . 

1 

3 

0 

0 

0 

2 

0 . 000 

5 . 00001 

296.15 

0 

z5 

0 

2 

0 

0 

2 

10 

0 

0 

0 

- 2 

0 . 000 

2 

296 . 15 

0 

ahsR 

0 

2 

0 

0 

3 

10 

0 

0 

1 

2 

0 . 000 

1 

296 . 15 

0 

ahsS 

0 

2 

0 

0 

4 

3 

0 

0 

0 

1 

0 . 000 

0 . 99999 

296 . 15 

0 

zl 

0 

2 

0 

0 

5 

3 

0 

0 

0 

1 

0 . 000 

2 

293 . 15 

0 

z2 

0 

2 

0 

0 

6 

3 

0 

0 

0 

1 

0 . 000 

3 

296 . 15 

0 

z3 

0 

2 

0 

0 

7 

3 

0 

0 

0 

1 

0 . 000 

4 

296 . 15 

0 

z4 

0 

2 

0 

0 

-999 

□ Section  15:  Initial  Zone  Concentrations 

Initial  zone  contaminant  mass  fractions  are  read  by  the  zone_read(  ) function  and  saved  by  the 
zone_save( ) function.  The  mass  fractions  are  stored  in  the  ZONE  DSC  structures  that  are 
defined  in  contam.h  for  ContamW  and  they  are  stored  in  an  array  in  ContamX. 

The  zone  contaminants  section  starts  with: 

nn  //  number  of  mass  fraction  that  follow  (14) 

nn  should  equal  nzone  * nctm. 

This  is  followed  by  nzone  lines  in  order  from  1 to  nzone. 

Each  data  line  contains  nctm  mass  fractions  ( R4 ) in  contaminant  order. 

nr 

CCO  [i]  [1]  //  initial  mass  fraction  (R4)  of  zone  i,  contaminant  1 


CCO  [i]  [_nctm]  //  initial  mass  fraction  (R4)  of  zone  i,  contaminant  _nctm 
The  initial  zone  concentrations  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 


Example: 


14  ! 
! Z# 
1 
2 

3 

4 

5 

6 
7 

-999 


initial  concentrations: 


Cl 

1 . 000e+000 
1 . 000e+000 
1 . 000e+000 
1 . 000e+000 
1 . 000e+000 
1 . 000e+000 
1 . 000e+000 


C2 

2 . 000e+000 
2 . 000e  + 000 
2 . 000e  + 000 
2 . 000e  + 000 
2 . 000e  + 000 
2 . 0 0 0e  + 0 0 0 
2 . 000e+000 


□ Section  16:  Airflow  Paths 

Path  data  are  read  by  the  path_read( ) function  and  saved  by  the  path_save( ) function.  The  data 
are  stored  in  the  PATH  DSC  structures  that  are  defined  in  contam.h  for  ContamW  and  simdat.h 
for  ContamX. 

The  path  section  starts  with: 
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_npath  //  number  of  paths  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  jipath  paths. 


For  each  path  the  data  line  includes: 

path  number  (12) ; in  order  from  1 to  _npath 
airflow  path  flag  values  (12) 
zone  N index  (12) ; converted  to  pointer 
zone  M index  (12) ; converted  to  pointer 
flow  element  index  (12) ; converted  to  pointer 
filter  index  (12) ; converted  to  pointer 
wind  coefficients  index  (12);  converted  to  pointer 
AHS  index  (12) ; converted  to  pointer 
schedule  index  (12) ; converted  to  pointer 
control  node  index  (12);  converted  to  pointer 
level  index  (12);  converted  to  pointer 
X-coordinate  of  envelope  path  [m]  (R4)  {Contam  2.1} 

Y-coordinate  of  envelope  path  [m]  (R4)  {Contam  2.1} 

height  relative  to  current  level  [m]  (R4) 

element  multiplier  (R4) 

constant  wind  pressure  [Pa]  (pw==NULL)  (R4) 
wind  speed(?)  modifier  (pw!=NULL)  (R4) 
wall  azimuth  angle  (pwi=NULL)  (R4) 

AHS  path  flow  rate  [kg/s]  (pw==NULL)  (R4) 
flow  or  pressure  limit  - maximum  (R4)  {w} 

flow  or  pressure  limit  - minimum  (R4)  {w} 

icon  used  to  represent  flow  path  (Ul)  {w} 

//  positive  flow  direction  on  sketchpad  (Ul)  {w} 
units  of  height  (12)  {w} 

units  of  pressure  difference  (12)  {w} 

units  of  flow  (12)  {w} 


nr 

// 

flags 

// 

pzn 

// 

pzm 

// 

pe 

// 

pf 

// 

pw 

// 

pa 

// 

ps 

// 

pc 

// 

pld 

// 

X 

// 

Y 

// 

relHt 

// 

mult 

// 

wPset 

// 

wPmod 

// 

wazm 

// 

Fahs 

// 

Xmax 

// 

Xmin 

// 

icon 

// 

dir 

// 

u_Ht 

// 

u_dP 

// 

u_F 

// 

The  paths  section  is  terminated  with: 

-999  //  used  to  check  for  a 


read  error  in  the  above  data 


Example: 

31  ! flow  paths: 


P# 

f 

n# 

m# 

e# 

f# 

w# 

a# 

s# 

c# 

1# 

X 

Y 

relHt 

mult  wPset  ’ 

wPmod 

wazm 

Fahs . . 

1 

8 

1 

2 

0 

0 

0 

1 

0 

0 

2 

0 . 000 

0 . 000 

0 . 000 

1 

0 

0 

0 

2 

0 

0 

129 

5 

0 

0 

0 

0 

2 

8 

3 

1 

0 

0 

0 

1 

0 

0 

2 

0 . 000 

0 . 000 

0 . 000 

1 

0 

0 

0 

1 

0 

0 

128 

2 

0 

0 

0 

0 

3 

7 

-1 

1 

12 

0 

1 

0 

0 

0 

2 

0 . 000 

0 . 000 

1 . 500 

1 

0 

0.36 

180 

0 

0 

0 

30 

1 

0 

0 

0 

0 

4 

7 

-1 

1 

12 

0 

2 

0 

0 

0 

2 

0 . 000 

0 . 000 

1 . 500 

2 

0 

0 .36 

180 

0 

0 

0 

23 

1 

0 

0 

0 

0 

5 

7 

-1 

4 

13 

0 

2 

0 

0 

0 

1 

19 . 000 

17 . 000 

1 . 500 

1 

0 

0 .36 

0 

0 

0 

0 

23 

4 

0 

0 

0 

0 

6 

6 

-1 

4 

8 

0 

0 

0 

0 

0 

1 

21 . 000 

17 . 000 

1 . 500 

1 

0 

0 

0 

-1 

0 

0 

23 

4 

0 

0 

0 

0 

30 

38 

-1 

3 

0 

1 

0 

0 

0 

0 

2 

17 .000 

5 . 000 

1 . 500 

1 

0 

0 

0 

-1 

0 

0 

0 

6 

0 

0 

0 

0 

31 

64 

2 

-1 

0 

0 

0 

0 

0 

0 

2 

0 . 000 

0 . 000 

1 . 500 

1 

0 

0 

0 

-1 

0 

0 

0 

6 

0 

0 

0 

0 

-999 


□ Section  17:  Duct  Junctions 

Junction  data  are  read  by  the  jct_read( ) function  and  saved  by  the  jct_save( ) function.  The  data 
are  stored  in  the  JCT  DSC  structures  that  are  defined  in  contam. h for  ContamW  and  simdat.h  for 
ContamX. 


Part  2 - Project  File  (.PRJ) 


The  junction  section  starts  with: 

_njct  //  number  of  junctions  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  njct  junctions. 

For  each  junction  the  data  line  includes: 

nr 

flags 
pzn 
pw 
dnr 
pk 
ps 
pc 
pld 
X 
Y 

relHt 
TO 
PO 

wPset 
wPmod 
wazm 
u_Ht 
u_T 
u_dP 
icon 
ddir 
f dir 

The  junctions  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

19  ! duct  junctions: 

! J#  f t z#  w#  dct  k#  s#  c#  1#  X Y relHt  TO  PO  wPset  wPmod  wazm  u.  . 

133-10  00002  17.000  21.000  0.000  296.15  000-10020  162  2 2 

230-10  00002  0.000  0.000  0.000  296.15  000-10020  158  0 0 

19  3110  00002  0.000  0.000  0.000  296.15  000-10020  162  1 1 

-999 


//  zone  number  (12) ; in  order  from  1 to  _nzone 
//  zone  flags  - bits  defined  in  contam.h  (U2) 

//  surrounding  zone  index  (12) ; converted  to  pointer 
//  wind  coefficients  index  (12);  converted  to  pointer 
//  duct  segment  number  - use  during  read  (12) 

//  kinetic  reaction  index  (12);  converted  to  pointer 
//  schedule  index  (12) ; converted  to  pointer 
//  control  node  index  (12) ; converted  to  pointer 
//  level  index  (12) ; converted  to  pointer 

//  X-coordinate  of  ambient  terminal  [m]  (R4)  {Contam  2.1} 

//  Y-coordinate  of  ambient  terminal  [m]  (R4)  {Contam  2.1} 

//  height  relative  to  current  level  [m]  (R4) 

//  initial  junction  temperature  [K]  (R4) 

//  initial  junction  pressure  [Pa]  (R4) 

//  constant  wind  pressure  [Pa]  (pw==NULL)  (R4) 

//  wind  speed  (?)  modifier  (pw!=NULL)  (R4) 

//  wall  azimuth  angle  (pwi=NULL)  (R4) 

//  units  of  height  (12)  {w} 

//  units  of  temperature  (12)  {w} 

//  units  of  pressure  difference  (12)  {w} 

//  icon  used  to  represent  flow  path  (Ul)  {w} 

//  direction  of  terminal  duct  - to  show  wP  (Ul)  {w} 

//  positive  flow  direction  - to  show  flow  (Ul)  {w} 


□ Section  18:  Initial  Junction  Concentrations 

Initial  junction  contaminant  mass  fractions  are  read  by  the  zone_read( ) function  and  saved  by 
the  zone_save(  ) function.  The  mass  fractions  are  stored  in  the  ZONE  DSC  structures  that  are 
defined  in  contam.h  for  ContamW  and  they  are  stored  in  an  array  in  ContamX. 

The  zone  contaminants  section  starts  with: 

nn  //  number  of  mass  fraction  that  follow  (14) 

nn  should  equal  nzone  * nctm.  This  is  followed  by  nzone  lines  in  order  from  zone  1 to  zone 
nzone. 
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Part  2 - Project  File  (,PRJ) 


Each  data  line  contains  nctm  mass  fractions  (R4)  in  contaminant  order. 

The  initial  zone  concentrations  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

38  ! initial  concentrations: 


! J# 

Cl 

C2 

1 

1 . 000e  + 000 

2 . 000e  + 000 

2 

1 . 000e+000 

2 . 000e  + 000 

3 

1 . 000e+000 

2 . 000e  + 000 

4 

1 . 000e+000 

2 . 000e+000 

5 

1 . 000e+000 

2 . 000e  + 000 

6 

1 . 000e+000 

2 . 000e+000 

7 

1 . 000e  + 000 

2 . 000e  + 000 

8 

1 . 000e+000 

2 . 000e+000 

9 

1 . 000e+000 

2 . 000e+000 

10 

1 . 000e  + 000 

2 . 000e+000 

11 

1 . 000e+000 

2 . 000e  + 000 

12 

1 . 000e  + 000 

2 . 000e+000 

13 

1 . 000e+000 

2 . 000e+000 

14 

1 . 000e  + 000 

2 . 000e  + 000 

15 

1 . 000e+000 

2 . 000e+000 

16 

1 . 000e+000 

2 . 000e  + 000 

17 

1 . 000e  + 000 

2 . 000e  + 000 

18 

1 . 000e+000 

2 . 000e+000 

19 

1 . 000e+000 

2 . 000e+000 

-999 

□ Section  19:  Duct  Segments 

Duct  data  are  read  by  the  duct_read( ) function  and  saved  by  the  duct_save( ) function.  The  data 
are  stored  in  the  DCT  DSC  structures  that  are  defined  in  contam.h  for  ContamW  and  simdat.h 
for  ContamX. 


The  path  section  starts  with: 

ndct  //  number  of  ducts 


12 


This  is  followed  by  a data  header  comment  line  and  then  data  for  all  ndct  ducts. 


For  each  duct  the  data  line  includes: 

duct  number  (12) ; 
duct  flag  values  ( 
junction  N index  ( 
junction  M index  ( 
duct  flow  element 
filter  index  (12) ; 
schedule  index  (12 


nr 

// 

flags 

// 

pjn 

// 

pjm 

// 

pe 

// 

Pf 

// 

ps 

// 

pc 

// 

dir 

// 

length 

// 

Ain 

// 

Aout 

// 

Sllc 

// 

in  order  from  1 to  _ndct 
12) 

12) ; converted  to  pointer 
12) ; converted  to  pointer 
index  (12) ; converted  to  pointer 
converted  to  pointer 
) ; converted  to  pointer 


control  node  index  (12) ; converted  to  pointer 
positive  flow  direction  on  sketchpad  (Ul)  { W } 
length  of  the  duct  segment  [m]  (R4) 

flow  area  at  inlet  end  [nf2]  - future  (R4) 

flow  area  at  outlet  end  [rrf2]  - future  (R4) 
sum  of  local  loss  coefficients  (R4) 


57 


Part  2 - Project  File  (.PRJ) 


Lam  //  laminar  loss  coefficient  (R4) 

u_L  //  units  for  length  (12)  { W } 

u_A  //  units  for  flow  area  (12)  { W } 

The  paths  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

18  ! duct  segments: 


! D# 

f 

n# 

m# 

e# 

f# 

s# 

c# 

dir 

len  Ain  Aout  sllc 

u . 

. . 

1 

0 

1 

2 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

2 

0 

2 

3 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

3 

0 

3 

4 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

4 

0 

4 

5 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

5 

0 

5 

6 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

6 

0 

6 

7 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

7 

0 

7 

8 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

8 

0 

8 

9 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

9 

0 

9 

10 

1 

0 

0 

0 

2 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

10 

0 

11 

2 

9 

0 

0 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

11 

0 

12 

3 

8 

0 

0 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

12 

0 

13 

4 

7 

0 

0 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

13 

0 

14 

5 

6 

0 

0 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

14 

0 

15 

6 

5 

0 

0 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

15 

0 

16 

7 

4 

0 

0 

0 

1 

5 

0 .15708 

0 . 15708 

0 

0 

0 

16 

0 

17 

8 

3 

0 

0 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

17 

0 

18 

9 

2 

0 

0 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

18  0 19 

-999 

□ Section  20 

10  1 0 0 

: Source/Sinks 

0 

1 

5 

0 . 15708 

0 . 15708 

0 

0 

0 

Contaminant  sources/sinks  are  read  by  the  css_read( ) function  and  saved  by  the  css_save( ) 
function.  The  data  are  stored  in  the  CSS  DSC  structures  that  are  defined  in  contain. h for 
ContamW  and  simdat.h  for  ContamX. 

The  source/sink  section  starts  with: 

_ncss  //  number  of  source/sinks 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  ness  source/ sinks. 

For  each  source/sink  the  data  line  includes: 

nr  //  source/sink  number  (12) ; in  order  from  1 to  _ncss 

pz  //  zone  index  (12);  converted  to  pointer 

pe  //  source/sink  element  index  (12);  converted  to  pointer 

ps  //  schedule  index  (12);  converted  to  pointer 

pc  //  control  node  index  (12) ; converted  to  pointer 

mult  //  multiplier  (R4) 

CCO  //  initial  mass  fraction  (some  types)  [kg/kg]  (R4) 

The  source/sink  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 
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Part  2 - Project  File  (.PRJ) 


Example: 


6 ! source/sinks : 


! # 

z# 

e# 

s# 

c# 

mult 

CCO 

1 

1 

1 

0 

0 

1 

0 

2 

1 

2 

0 

0 

1 

0 

3 

1 

3 

0 

0 

1 

0 

4 

1 

4 

0 

0 

1 

0 

5 

1 

5 

0 

0 

1 

0 

6 

-999 

1 

6 

1 

0 

1 

0 

□ Section  21:  Occupancy  Schedules 

Occupancy  schedules  are  read  by  the  oschd_read( ) function  and  saved  by  the  oschd_save( ) 
function.  The  data  are  stored  in  the  ODSCHD  structures  that  are  defined  in  contam.h  for 
ContamW  and  simdat.h  for  ContamX. 

The  occupancy  schedule  section  starts  with: 

_nosch  //  number  of  schedules  (12) 

This  is  followed  by  a data  header  comment  line  and  then  data  for  all  nosch  schedules. 

For  each  schedule  the  first  data  line  includes: 

nr  //  schedule  number  (12) ; in  order  from  1 to  _nosch 

npts  //  number  of  points  (12) 

name []  //  schedule  name  (II)  {w} 

and  the  second  line  has: 

desc  []  //  schedule  description  (II)  {w}  may  be  blank 

This  is  followed  by  npts  lines  of  schedule  data: 

time  //  time-of-day  [s]  (hh:mm:ss  converted  to  14) 

pz  //  zone  index  (12) ; converted  to  pointer 

The  occupancy  schedule  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

1 ! occupancy  schedules: 

1 3 OccDySchedl 

Occupant  day  schedule  one . 

00:00:00  0 
00:12:00  4 
24:00:004 
-999 

□ Section  22:  Exposures 

Exposure  data  are  read  by  the  pexp_read( ) function  and  saved  by  the  pexp_save( ) function.  The 
data  are  stored  in  the  PEXP  DSC  structures  that  are  defined  in  contam.h  for  ContamW  and 
simdat.h  for  ContamX. 

The  exposure  section  starts  with: 

_npexp  //  number  of  exposures  (12) 
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Part  2 - Project  File  (.PRJ) 


This  is  followed  by 
For  each  exposure 


three  lines  of  data  for  all  npexp  exposures, 
the  first  data  line  includes: 


nr 

// 

exposure  number  (12) ; 

in  order  from  1 

to  npexp 

gen 

// 

= 1 if  contaminants  are  generated 

(12) 

ncg 

// 

number  of  contaminant 

generations 

(12) 

cgmlt 

// 

contaminant  generation  multiplier 

[-] 

(R4 ) 

inhmax 

// 

peak  inhalation  rate 

[mA3/s]  (R4) 

{unused} 

inhsch 

// 

weekly  inhalation  schedule  index  < 

:i2) 

bodywt 

// 

body  weight  [kg]  (R4) 

{unused} 

u inh 

// 

units  for  inhalation 

rate  (12) 

u bw 

// 

units  for  body  weight 

(12) 

The  second  line  has  the  exposure  description: 

desc  []  //  exposure/person  description 


II 


The  third  line  has  the  indices  of  12  occupancy  schedules: 

odsch[12]  //  vector  of  daily  occupancy  schedules  - 12  indices 


It  is  followed  by  ncg  lines  of  contaminant  generation  data: 

name  //  species  name  (II) 

ps  //  schedule  index  (12) ; converted  to  pointer 

cgmax  //  peak  generation  rate  [kg/s]  (R4) 
u_cg  //  units  of  generation  rate  (12)  {w} 

The  exposure  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 


Example: 

2 ! exposures : 

1121  0.000334444  1 70  4 0 
Occupant  one . 

111111111111  ! occ.  schd 
Cl  1 1 0 1 occ . gen 

C2  1 2 0 ! occ . gen 

2021  0.000668889  1 80  4 0 
Occupant  two. 

111111111111  ! occ.  schd 
Cl  0 1 0 ! occ . gen 

C2  1 2 0 ! occ . gen 

-999 


60 


Part  2 - Weather  File  (.WTH) 


□ Section  23:  Annotations 

Annotations  are  read  by  the  note_read( ) function  and  saved  by  the  note_save( ) function.  The 
data  are  stored  in  the  NOTE  DSC  structures  that  are  defined  in  contain. h.  Annotations  are  used 
only  in  ContamW;  nothing  is  stored  when  this  section  is  read  in  ContamX. 

The  annotations  section  starts  with: 

_nnote  //  number  of  annotations  (12) 

This  is  followed  by  data  for  all  nnote  annotations: 

For  each  annotation  data  line  includes: 

nr  //  annotation  number  (12)  {w};  in  order  from  1 to  _nnode 

note  []  //  annotation  (II)  { W } 

The  annotations  section  is  terminated  with: 

-999  //  used  to  check  for  a read  error  in  the  above  data 

Example: 

6 ! annotations: 

1 PLR_type  Airflow  Elements 

2 to  force  flows  through  PLR  paths 

3 QF_type  Airflow  Elements 

4 DR_type  Airflow  Elements 

5 PL_type  Airflow  Elements 

6 FN_type  Airflow  Elements 
-999 


2.4.2  Weather  File  (.WTH) 

Ambient  weather  conditions  are  made  available  to  ContamX  through  the  weather  file  which  has 
a .WTH  file  extension.  Use  this  file  when  performing  transient  simulations  and  you  need  to  vary 
the  ambient  conditions  with  time.  If  you  need  to  specify  wind  pressures  that  vary  with  time  and 
spatially  around  the  building  envelope,  you  should  consider  using  a WPC  file  (See  Working  with 
WPC  Files). 

The  first  line  of  the  weather  file  is  used  to  identify ; the  type  of  file.  It  is  exactly: 

WeatherFile  ContamW  2.0 

The  second  line  is  a description  of  the  file  entered  by  the  user: 

desc  []  //  file  description  (II)  {w};  may  be  blank 

Succeeding  lines  contain: 

StartDate  //  first  date  for  weather  data  (mm/dd  — > IX) 

EndDate  //  last  date  for  weather  data  (mm/dd  — > IX) 


These  are  followed  by  a header  line  for  the  date  data: 
IDate  DofW  Dtype  DST  Tgrnd 


Day  data  for  each  date  from  StartDate  to  EndDate: 

date  //  date  (mm/dd  — > IX) 

dayofwk  //  day  of  week  [l  = Sun  ...  7=Sat]  (12) 

daytype  //  type  of  day  for  schedule  reference  [1-12]  (12) 

DST  //  daylight  savings  time  [0  / 1 = DST  in  effect]  (12 

Tground  //  ground  temperature  [K]  (R4) 
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Part  2 - Weather  File  (.  WTH) 


These  are  followed  by  a header  line  for  the  weather  data: 

!Date  Time  Ta  Pb  Ws  Wd  Hr  Ith  Idn  Ts  Rn  Sn 


Weather  data  for  each  date  from  StartDate  to  EndDate: 

date  (mm/dd  — > IX) 
time  of  day  (hh:mm:ss  — > 14) 
ambient  temperature  [K]  (R4 


;R4) 


date 

// 

time 

// 

tmpambt 

// 

barpres 

// 

windspd 

// 

winddir 

// 

humrat io 

// 

solhtot 

// 

solhdif 

// 

t skyef  f 

// 

rain 

// 

snow 

// 

[Pa]  (R4 


:r4 


:r4 


total  solar  flux  on  horizontal  surface  [W/m  2]  (R4) 

//  diffuse  solar  flux  on  horizontal  surface  [W/nf2]  (R4 

effective  sky  temperature  [K]  (R4) 

rain  indicator  [0  or  1]  (12) 

snow  indicator  [0  or  1]  (12) 


The  file  description  may  not  begin  with  a T.  The  StartDate  and  EndDate  are  used  to  verily  that 
the  file  data  covers  the  entire  period  to  be  simulated.  The  StartDate  may  not  be  later  than  the 
EndDate. 


The  weather  data  must  start  at  time  00:00:00  on  the  StartDate  and  end  at  24:00:00  on  the 
EndDate.  The  times  must  be  in  consecutive  order,  but  the  difference  between  successive  times 
need  not  be  constant. 


NOTE:  Be  sure  to  set  the  date  formats  as  shown  in  the  sample  below  when  editing/saving  tab- 
delimited  files  with  a spreadsheet  program 


The  ground  temperature  and  solar  flux  through  snow  cover  data  will  be  used  if  the  program  is 
expanded  for  full  thermal  simulation.  At  present  place  holder  values  (e.g.,  0)  may  be  used. 


Example: 


WeatherFile  ContamW  2 . 0 
Weather  for  Janl  - Jan3 


1/1 

1/3 

1 Date 

Dof  W 

Dtype 

DST 

Tgrnd 

1/1 

4 

4 

0 

281 . 6 

1/2 

5 

5 

0 

281 . 57 

1/3 

6 

6 

0 

281 . 54 

i Date 

Time 

Ta 

Pb 

Ws 

1/1 

00  : 

00 

: 00 

275 

. 15 

100000 

3 . 

6 

1/1 

01 : 

00 

: 00 

275 

.15 

100000 

3 . 

1 

1/1 

02  : 

00  : 

: 00 

275 

. 15 

100000 

2 . 

1 

1/1 

24  : 

00 

: 00 

273 

. 15 

100000 

4 . 

6 

1/2 

01  : 

00  : 

: 00 

273 

. 15 

100000 

2 . 

1 

1/2 

02  : 

00  : 

: 00 

272 

. 15 

100000 

4 . 

1 

1/2 

24  : 

00  : 

: 00 

272 

. 15 

100000 

1 . 

5 

1/3 

01  : 

00 

: 00 

272 

. 15 

100000 

1 

1/3 

02  : 

00 

: 00 

272 

. 15 

100000 

2 . 

6 

1/3 

24  : 

00 

: 00 

282 

. 15 

100000 

5 . 

7 

Wd 

Hr 

Ith 

Idn 

Ts 

Rn 

Sn 

290 

2 . 

213 

0 

0 

259  , 

. 442 

0 

0 

300 

2 . 

213 

0 

0 

259  . 

. 442 

0 

0 

300 

2 . 

213 

0 

0 

259  . 

. 442 

0 

0 

320 

1 . 

915 

0 

0 

256  . 

. 627 

0 

0 

330 

1 . 

915 

0 

0 

256  . 

. 627 

0 

0 

330 

1 . 

763 

0 

0 

255  . 

.899 

0 

0 

230 

1 . 

763 

0 

0 

255  . 

.899 

0 

0 

210 

1 . 

763 

0 

0 

255  . 

.899 

0 

0 

260 

1 . 

763 

0 

0 

255  . 

.899 

0 

0 

230 

3 . 

607 

0 

0 

268  . 

.353 

0 

0 
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2.4.3  Contaminant  File  (.CTM) 

I rnnsient  ambient  species  data  is  made  available  to  ContamX  through  the  contaminant  file  which 
h.is  a .CTM  file  extension.  Use  this  file  when  performing  transient  simulations  and  you  want  the 
ambient  concentration  to  be  represented  by  a single  value  at  each  time  step.  If  you  need  the 
ambient  concentration  to  vary  spatially  as  well  over  the  building  envelope,  then  you  should  use 
the  . WPC  file  (see  Working  with  WPC  Files  in  Part  1). 

I lie  first  line  of  the  contaminant  fife  is  used  to  identify  the  type  of  file.  It  is  exactly: 

; "ciesFile  ContamW  2.0 


l he  second  line  is  a description  of  the  file  entered  by  the  user: 

i-'sc  []  //  file  description  (II)  {w}  ; may  be  blank 


Succeeding  lines  contain: 

kartDate  //  first  date  for  contaminant  data  (mm/dd  — > IX) 

EndDate  //  last  date  for  contaminant  data  (mm/dd  — > IX) 

NumCont  //  number  of  contaminants  (12) 

I 1 Name [1]  //  name  of  contaminant  1 (11-16  characters  maxi 

I i Name [2]  //  name  of  contaminant  2 (II) 


Mime [NumCont]  //  name  of  contaminant  NumCont  (II) 


The  last  name  is  followed  by  a header  line  for  the  remaining  data: 
IDate  Time  Name [1]  Name [2]  ...  Name [NumCont] 


Then  comes  concentration  data  for  each  time  step: 

date  //  date  (mm/dd  — > IX) 

time  //  time  of  day  (hh:mm:ss  — > 14) 

cone  [1]  //  concentration  of  contaminant  1 

cone  [2]  //  concentration  of  contaminant  2 


(R4) 

(R4) 


cone [NumCont]  //  concentration  of  contaminant  NumCont  (R4) 

The  file  description  may  not  begin  with  a ‘ ! ’.  The  StartDate  and  EndDate  are  used  to  verily  that 
the  file  data  covers  the  entire  period  to  be  simulated.  The  StartDate  may  not  be  later  than  the 
EndDate.  The  contaminant  names  are  matched  against  the  names  of  the  contaminants  to  be 
simulated.  Concentrations  for  names  that  do  not  match  will  be  ignored. 

The  concentration  data  must  start  at  time  00:00:00  on  the  StartDate  and  end  at  24:00:00  on  the 
EndDate.  The  times  must  be  in  consecutive  order,  but  the  difference  between  successive  times 
need  not  be  constant.  Concentrations  are  given  in  units  of  mass  (or  density)  of  contaminant  per 
mass  (or  density)  of  air,  air  being  the  sum  of  all  species  including  non-contaminants. 

NOTE:  Be  sure  to  set  the  date  formats  as  shown  in  the  sample  below  when  editing/saving  tab- 
delimited  files  with  a spreadsheet  program 

Example: 

SpeciesFile  ContamW  2 . 0 

Demo  ctm  file  for  Jan  1 - Jan  3 


1/1 

1/3 

2 

CO 

C02 

! Date 

Time 

CO 

C02 

1/1 

0:00:00 

9 . 17E-07 

5 . 23E-04 

1/1 

1:00:00 

9 . 17E-07 

5 . 23E-04 
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1/1 

2 : 

00  : 

00 

9 . 17E-07 

5 . 23E-04 

1/2 

24 

: 00 

: 00 

9 . 17E-07 

5 . 23E-04 

1/2 

1 : 

00  : 

00 

9 . 17E-07 

5 . 23E-04 

1/2 

2 : 

00  : 

00 

9 . 17E-07 

5 . 23E-04 

1/3 

24 

: 00 

: 00 

9 . 17E-07 

5 . 23E-04 

1/3 

1 : 

00  : 

00 

9 . 17E-07 

5 . 23E-04 

1/3 

2 : 

00  : 

00 

9 . 17E-07 

5 . 23E-04 

1/3 

24 

: 00 

: 00 

1 . 41E-06 

5 . 23E-04 

2.4.4  Restart  File  (.RST) 

Restart  is  an  alternative  to  normal  initialization.  ContamX  will  either  read  the  restart  file  or 
create  it.  Creation  may  occur  only  for  transient  simulations  starting  at  00:00:00  and  ending  at 
24:00:00,  on  the  same  or  different  days.  A restart  file  will  have  data  at  24:00:00  of  all  days 
simulated.  If  the  run  is  not  cyclic,  it  will  also  have  data  at  00:00:00  of  the  first  day  simulated. 


All  code  is  contained  in  file  restart.c  with  file  'globals'. 

IX  set_urst ( IX  flag  ) ; 

flag  = 0:  initialize  parameters. 

flag  = 1:  open  restart  file  _urst;  write  header 
flag  = 2:  close  restart  file, 
flag  = 3:  remove  restart  file. 


data . 


void  resout ( IX  date,  14  time  ) ; 

if  _urst  open,  write  current  date/time  restart  data. 


void  resget ( IX  rstdate,  14  rsttime  ); 
read  rstdate/rstt ime  restart  data. 


HEADER  DATA: 

m [0] 

= 

0L; 

/*  TURBO 

C+  + 

messes  up  the  first 

m [1] 

= 

(14) 

nzone ; 

/*  therefore,  send  4 

m [2] 

= 

(14) 

npath ; 

m [3  ] 

= 

(14) 

nctm; 

m [4] 

= 

(14) 

nj  ct  ; 

m [5] 

= 

(14) 

ndct  ; 

m [6] 

= 

(14) 

ness  ; 

m [7] 

(14) 

nctrl ; 

m [8] 

- 

(14) 

redat . date 

_0  ; 

m [9] 

= 

(14) 

redat . date 

_1  ; 

m [10] 

= 

(14) 

rSizeData ; 

m [11] 

= 

(not 

set ) 

bytes  written 
unused  bytes. 


*/ 

*/ 


m[l]  thru  m[7]  allow  ContamW  to  check  for  some  changes  in  the  project. 
m[8]  and  m[9]  are  the  date  limits  displayed  to  the  user. 
m[ll]  will  allow  reading  all  dates  on  the  file  --  could  be  used  to 
create  a selection  box  of  available  dates. 

RESTART  DATA: 

For  all  AF_NODEs : 

R8  T - temperature 
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R8  P - pressure 
R8  M - mass 

R4  Mf [_nctm]  - mass  fractions 

For  all  AF_PATHs : 

R8  Flow[0]  - primary  flow 
R8  Flow[l]  - secondary  flow 
R8  dP  - pressure  drop 

For  CSS_DSC: 

CSE_EDS  ( 14 ) pss- >local  (stored  as  R4 , converted  to  14  in  simulation) 

CSE_BLS  ( R4 ) pss->local 

For  CT_NODEs : 

SNSDAT : R4  oldsig 

PI CD AT : R4  oldsig,  R4  olderr 

HYSDAT : R4  oldsig 

2.4.5  Continuous  Values  File  (.CVF) 

Control  node  values  that  change  linearly  in  time  are  made  available  to  ContamX  through  the 
continuous  values  file  which  has  a .CVF  file  extension. 

The  first  line  of  the  CVF  is  used  to  identify  the  type  of file.  It  is  exactly: 

ContinuousValuesFile  ContamW  2.1 

The  second  line  is  a description  of  the  file  entered  by  the  user: 

desc  []  //  file  description  (II)  {w} ; may  be  blank 

The  next  two  lines  de  fine  the  period  covered  by  the  file: 

StartDate  //  first  date  for  DEF  data  (mm/dd  — > IX) 

EndDate  //  last  date  for  DEF  data  (mm/dd  — ■>  IX) 

The  next  section  specifies  the  control  node  names: 

_nbvfn  //  number  of  CVF  node  names 

followed  by  nbvfn  lines  consisting  of  node  names: 

name []  //  node  name  (II) 

The  remainder  of  the  file  consists  of  data  for  all  nodes  for  each  date  and  time  from  StartDate  to 
EndDate: 

date  //  date  (mm/dd  — > IX) 

time  //  time  of  day  (hh:mm:ss  -a  14) 

value  [1]  //  value  [?]  for  name [1]  (R4) 

value [_nbvf]  //  value  [?] for  name [_nbvf ] (R4) 

The  node  data  must  start  at  time  00:00:00  on  the  StartDate  and  end  at  24:00:00  on  the  EndDate. 
The  times  must  be  in  consecutive  order,  but  the  difference  between  successive  times  need  not  be 
constant. 

The  file  description  may  not  begin  with  a 4 ! \ The  StartDate  and  EndDate  are  used  to  verity  that 
the  file  data  covers  the  entire  period  to  be  simulated.  The  StartDate  may  not  be  later  than  the 
EndDate.  Data  elements  on  a single  line  are  separated  by  tabs.  The  data  must  be  in  time- 
sequential  order.  The  file  values  must  be  in  the  units  needed  for  the  signal  created  by  the  control 
node.  Be  sure  to  include  a data  line  at  the  end  of  each  day  - 24:00:00. 
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Node  names  may  not  include  imbedded  blanks.  Data  for  nodes  that  are  not  in  the  project  file 
will  be  ignored.  If  a CVF  node  name  in  the  project  file  is  not  included  in  the  CVF,  a fatal  error 
will  result.  ContamW  will  assist  the  user  by  checking  node  names.  ContamX  will  perform  the 
name  check  before  simulation  begins. 

Example: 

ContinuousValuesFile  ContamW  2.1 
Sample  CVF  file 
1/1  1/3 
4 

nodel 

node2 

node3 

node4 


1/1 

00  : 

: 00  : 

: 00 

0 . 

. 0 

0 . 

. 5 

0 . 

. 5 

1 . 

. 0 

1/1 

04  : 

: 00  : 

: 00 

1 . 

. 0 

0 . 

. 0 

1 . 

. 0 

0 . 

. 0 

1/1 

08  : 

: 00  : 

: 00 

0 . 

. 5 

0 . 

. 5 

0 . 

. 5 

0 . 

. 5 

1/1 

12  : 

: 00  : 

: 00 

0 . 

. 0 

1 . 

. 0 

0 . 

. 0 

1 . 

. 0 

1/1 

16  : 

: 00  : 

: 00 

1 . 

. 0 

0 . 

. 5 

0 . 

. 5 

0 . 

. 0 

1/1 

24  : 

: 00  : 

: 00 

0 . 

. 0 

0 . 

. 5 

0 . 

. 5 

1 . 

. 0 

1/2 

04  : 

: 00  : 

: 00 

1 . 

. 0 

0 . 

. 0 

1 . 

. 0 

0 . 

. 0 

1/2 

08  : 

: 00  : 

: 00 

0 . 

. 5 

0 . 

. 5 

0 . 

. 5 

0 . 

. 5 

1/2 

12  : 

: 00  : 

: 00 

0 . 

. 0 

1 . 

. 0 

0 . 

. 0 

1 . 

. 0 

1/2 

16  : 

: 00  : 

: 00 

1 . 

. 0 

0 . 

. 5 

0 . 

. 5 

0 . 

. 0 

1/2 

24  : 

: 00  : 

: 00 

0 . 

. 0 

0 . 

. 5 

0 . 

. 5 

1 . 

. 0 

1/3 

04  : 

: 00  : 

: 00 

1 . 

. 0 

0 . 

. 0 

1 . 

. 0 

0 . 

. 0 

1/3 

08  : 

: 00  : 

: 00 

0 . 

, 5 

0 . 

, 5 

0 . 

, 5 

0 . 

. 5 

1/3 

12  : 

: 00  : 

: 00 

0 . 

, 0 

1 . 

. 0 

0 . 

, 0 

1 . 

. 0 

1/3 

16  : 

: 00  : 

: 00 

1 . 

. 0 

0 . 

. 5 

0 . 

. 5 

0 . 

. 0 

1/3 

24  : 

: 00  : 

: 00 

0 . 

. 0 

0 . 

. 5 

0 . 

. 5 

1 . 

. 0 

2.4.6  Discrete  Values  File  (.DVF) 

Control  nodes  values  that  change  discretely  in  time  are  made  available  to  ContamX  through  the 
discrete  values  file  which  has  a .DVF  file  name  extension. 

The  first  line  of  the  DVF  is  used  to  identify ’ the  type  of  file.  It  is  exactly: 

DiscreteValuesFile  ContamW  2.1 

The  second  line  is  a description  of  the  file  entered  by  the  user: 

desc  []  //  file  description  (II)  {w} ; may  be  blank 

The  next  two  lines  define  the  period  covered  by  the  fde: 

StartDate  //  first  date  for  DEF  data  (mm/dd  — > IX) 

EndDate  //  last  date  for  DEF  data  (mm/dd  — > IX) 

The  next  section  specifies  the  control  node  names: 

_ndefn  //  number  of  DVF  node  names 

followed  by  ndefn  lines  consisting  of: 
name []  //  node  name  (II) 

value  //  initial  value  [?]  (R4) 

Succeeding  lines  present  data  whenever  a node  value  changes: 

date  //  date  (mm/dd  — » IX) 
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time  //  time  of  day  (hh:mm:ss  — » 14) 

name []  //  node  name  (II) 

value  //  new  value  [?]  (R4) 

The  file  description  may  not  begin  with  a 4 ! \ The  StartDate  and  EndDate  are  used  to  verify  that 
the  file  data  covers  the  entire  period  to  be  simulated.  The  StartDate  may  not  be  later  than  the 
EndDate.  Data  elements  on  a single  line  are  separated  by  tabs.  The  data  must  be  in  time- 
sequential  order.  More  than  one  node  may  change  at  the  same  time  with  each  node  listed  on  a 
separate  line.  The  file  values  must  be  in  the  units  needed  for  the  signal  created  by  the  control 
node.  Each  day  should  end  with  a line  of  the  form:  date  24:00:00  0 0. 

Node  names  may  not  include  imbedded  blanks.  Data  for  nodes  that  are  not  in  the  project  file 
will  be  ignored.  If  a DVF  node  name  in  the  project  file  is  not  included  in  the  DVF,  a fatal  error 
will  result.  ContamW  will  assist  the  user  by  checking  node  names.  ContamX  will  perform  the 
name  check  before  simulation  begins. 

Example: 

DiscreteValuesFile  ContamW  2.1 
Sample  DVF  file 
01/1  01/03 
4 

nodel  0 . 0 
node2  0 . 5 
node 3 0 . 5 
node4  1 . 0 

1/1  02:00:00  1 0.75 
1/1  02:30:00  3 0.25 
1/1  03:00:00  4 0.00 
1/1  08:00:00  2 1.00 
1/1  12:45:00  1 1.00 
1/1  21:30:00  1 0.75 
1/1  24:00:00  0 0.00 
1/2  01:30:00  1 0.00 
1/2  07:59:59  3 0.25 
1/2  23:30:00  1 0.75 
1/2  24:00:00  0 0.00 
1/3  18:00:00  3 1.00 
1/3  24:00:00  0 0.00 

2.4.7  Simulation  Results  File  (.SIM) 

The  results  of  the  ContamX  simulation  are  communicated  back  to  the  ContamW  program  in  the 
simulation  results  file.  This  file  will  be  created  in  the  same  directory  as  the  project  file  with  the 
name  of  the  project  file  and  the  .SIM  extension  appended.  The  format  of  this  file  has  not 
changed  since  the  Contam96  DOS  version  of  the  program.  It  is  a binary  file  for  faster  access  and 
smaller  size  than  a text  file.  It  can  be  read  and  reported  as  text  by  the  SIMREAD.EXE  program 
available  from  NIST. 

The  first  16  lines  of  the  simulation  results  file  contain  data  (32-bit  integers)  to  help  assure  that 
the  results  apply  to  the  project  file  currently  in  ContamW  and  to  set  the  array  sizes  necessary  to 
process  the  results. 

0 //  spacer  (to  avoid  a TurboC  bug)  (14) 

_nzone  //  number  of  airflow  zones  (excluding  ambient)  (14) 
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npath 

// 

nctm 

// 

time  list 

// 

date  0 

// 

time  0 

// 

date  1 

// 

time  1 

// 

pf save 

// 

zf save 

// 

zcsave 

// 

naf  nd 

// 

nccnd 

// 

naf  pt 

// 

number  of  airflow  paths  (14) 

number  of  contaminants  (14) 

listing  time  steps  [s] (14) 

start  of  simulation  - day  of  year  (14) 

start  of  simulation  - time  of  day  (14) 

end  of  simulation  - day  of  year  (14) 

end  of  simulation  - time  of  day  (14) 

if  true,  write  path  flow  results  (14) 

if  true,  write  zone  flow  results  (14) 

if  true,  write  zone  contaminant  results  (14) 

number  of  airflow  nodes  (zones  + junctions)  (14) 

number  of  contaminant  nodes  (zones  + junctions)  (14) 

number  of  airflow  paths  (paths  + ducts)  (14) 


This  is  followed  by  _nafnd  lines  of  airflow  node  cross-reference  data: 
typ  //  source  of  node  [zone  or  junction]  (U2) 

nr  //  zone  or  junction  number  (U2) 


The  next  _nafnd  lines  give  the  contaminant  node  cross-reference  data: 
typ  //  source  of  node  [zone  or  junction]  (U2) 

nr  //  zone  or  junction  number  (U2) 


The  next  _nafpt  lines  give  the  airflow  path  cross-reference  data: 

typ  //  source  of  path  [path,  duct,  or  leak]  (U2) 

nr  //  path,  duct,  or  leak  number  (U2) 


The  simulation  results  for  each  day  consist  of: 

The  results  for  each  time  step  consist  of: 


A line  of  time  and  ambient  data: 

dayof y 

// 

day  of  year  [1  to  365]  (12) 

daytyp 

// 

type  of  day  [1  to  12]  (12) 

sim  time 

// 

time  value  [s]  [0  to  86400]  (14) 

Tambt 

// 

ambient  temperature  [k]  (R4) 

P 

// 

barometric  pressure  [Pa]  (R4) 

Ws 

// 

wind  speed  [m/s]  (R4) 

Wd 

// 

wind  angle  [deg]  (R4) 

CC  [0] 

// 

ambient  mass  fraction  of  species 

[kg/kg] 


(R4) 


CC  [n]  //  ambient  mass  fraction  of  species  n [kg/kg]  (R4) 

A line  of  data  for  each  airflow  path: 

nr  //  path  number;  use  as  check  (12) 

dP  //  pressure  drop  across  path  [Pa]  (R4) 

FlowO  //  primary  flow  value  [kg/s]  (R4) 

Flowl  //  alternate  flow  value  [kg/s]  (R4) 

A line  of  data  for  each  airflow  node  (excluding  ambient): 

nr  //  node  number;  use  as  check  (12) 

T //  node  temperature  [K]  (R4) 

P //  node  reference  pressure  [Pa]  (R4) 

D //  node  air  density  [kg/m^3]  (R4) 

A line  of  data  for  each  contaminant  node  (excluding  ambient): 

nr  //  node  number;  use  as  check  (12) 

CC[0]  //  mass  fraction  of  species  0 [kg/kg]  (R4) 
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CC [n]  //  mass  fraction  of  species  n [kg/kg]  (R4) 

The  time  step  data  is  followed  by  summary  data  for  the  day. 

It  begins  with  the  following  line  of  ambient  data: 

dayofy  //  day  of  year  [1  to  365]  (12) 

daytyp  //  type  of  day  [1  to  12]  (12) 

Tamax  //  maximum  ambient  temperature  [k]  (R4) 

Tamin  //  minimum  ambient  temperature  [k]  (R4) 

Pavg  //  average  barometric  pressure  [Pa]  (R4) 

Wsmax  //  maximum  wind  speed  [m/s]  (R4) 

Wsavg  //  average  wind  speed  [m/s]  (R4) 

CC[0]  //  maximum  ambient  mass  fraction  of  species  0 [kg/kg]  (R4) 


CC [n]  //  maximum  ambient  mass  fraction  of  species  n [kg/kg]  (R4) 

A line  of  data  for  each  airflow  path: 

nr  //  path  number;  use  as  check  (12) 

dPmax  //  maximum  pressure  drop  across  path  [Pa]  (R4) 

Flowmax  //  maximum  primary  flow  value  [kg/s]  (R4) 

0.0  //  place  holder  (R4) 

A line  of  data  for  each  airflow  node  (excluding  ambient): 

nr  //  node  number;  use  as  check  (12) 

T //  node  temperature  [K]  (R4) 

P //  node  reference  pressure  [Pa]  (R4) 

D //  node  air  density  [kg/rrf3]  (R4) 

A line  of  data  for  each  contaminant  node  (excluding  ambient): 

nr  //  node  number;  use  as  check  (12) 

CCmax[0]  //  maximum  mass  fraction  of  species  0 [kg/kg]  (R4) 


CCmax [n]  //  maximum  mass  fraction  of  species  n [kg/kg] 


Note:  this  file  requires  that  the  structures  in  ContamW  and  ContamX  be  compiled  using  no 
greater  than  2-byte  member  alignment  (under  Visual  C++).  The  file  is  unreadable  if  the  default 
structure  member  alignment  is  used. 

2.4.8  Controls  Log  File  (.LOG) 

The  output  from  report  control  elements , are  written  to  the  controls  log  file.  This  file  will  be 
created  in  the  same  directory  as  the  project  file  with  the  name  of  the  project  file  and  the  .LOG 
extension  appended.  For  example  if  the  project  is  MyProj.PRJ , ContamX  will  create  the  file 
MyProj.LOG.  Values  will  be  reported  for  each  listing  time  step  of  a transient  simulation.  The  file 
is  tab-delimited  so  it  can  be  easily  imported  into  a spreadsheet  program. 

The  first  line  of  the  Controls  LOG  file  is  a comment  line  that  contains  a list  of  the  headers  for 
each  report  control  element.  These  headers  are  created  by  the  user. 

The  second  line  is  a comment  line  that  contains  column  headings  indicating  Date,  Time  and  the 
units  of  each  reported  value. 

Succeeding  lines  contain: 

Data  from  00:00:00  of  Start  Date  to  24:00:00  of  EndDate: 
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At  each  time: 

date 

time 

output [1] 
output [2] 


//  date  (mm/dd  — > IX) 

//  time  of  day  (hh:mm:ss  — > 14) 

//  outputs  for  each  report  control  (R4) 


output [number  of  report  controls] 


2.4.9  Wind  Pressure  and  Contaminant  File  (.WPC) 

This  file  provides  ambient  pressure  and  contaminant  concentrations  values  for  every  flow  path 
that  connects  to  ambient.  See  section  Working  with  WPC  Files  in  PART  1 for  information  on 
using  this  file  in  CONTAM. 

The  first  line  of  the  WPC  file  is  used  to  identify  the  type  of  file.  It  is  exactly: 

WPCFile  ContamW  2.1 

The  second  line  is  a description  of  the  file  entered  by  the  user: 

desc  []  //  file  description  (II)  {w};  may  be  blank 


12)  [0  possible] 


Succeeding  lines  contain: 

NumPath  //  number  of  flow  paths  (12) 

NumCont  //  number  of  contaminants  (species' 

UsePres  //  1 = use  pressures,  0 = don't  (12) 

dtmin  //  minimum  time  step  (12) 

StartDate  //  first  date  for  WPC  data  (mm/dd  — » IX) 

EndDate  //  last  date  for  WPC  data  (mm/dd  -a  IX) 

II  Name [1]  //  name  of  contaminant  1 (II  - 16  characters  max) 

II  Name [2]  //  name  of  contaminant  2 (II) 


Name [NumCont]  //  name  of  contaminant  NumCont  (II 


The  next  NumPath  lines  describe  each  flow  path: 


number 

X 

Y 

Z 

map 


//  sequence  number  (12) 

//  X-coordinate  (R4) 

//  X-coordinate  (R4) 

//  Z-coordinate  (R4) 

//  mapping  [0  = OK;  1 = error] 


(12) 


Data  from  00:00:00  of  StartDate  to  24:00:00  of  EndDate: 
At  each  time: 

First  line: 


date 

// 

date  (mm/dd 

IX) 

time 

// 

time  of  day 

( hh : mm : s s 

-4  14) 

pres 

// 

ambient  pressure  [Pa] 

( R4 ) (if  pressures  are  used) 

dens 

// 

air  density 

[kg/m3]  (R4 ) (if pressures  are  used) 

Second  line:  (if  pressures  are  used) 

pres  [1]  //  absolute  ambient  pressure  at  path[l]  [Pa]  (R4) 


pres [NumPath]  //  absolute  ambient  pressure  at  path [NumPath]  [Pa]  (R4) 

Third  line  (for  first  contaminant,  if  NumCont  > l): 

cone  [1]  //  concentration  at  path[l]  [kg/kg  air]  (R4) 
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cone [NumPath]  //  concentration  at  path [NumPath]  [kg/kg  air]  (R4) 
Fourth  line  (for  second  contaminant,  if  needed): 


Last  line  ( for  contaminant  NumCont,  if  needed): 

cone  [1]  //  concentration  at  path[l]  [kg/kg  air]  (R4) 


cone [NumPath]  //  concentration  at  path [NumPath]  [kg/kg  air]  (R4) 

The  file  description  may  not  begin  with  a 4 ! \ The  StartDate  and  EndDate  are  used  to  verify  that 
the  file  data  covers  the  entire  period  to  be  simulated.  The  StartDate  may  not  be  later  than  the 
EndDate. 


The  data  must  start  at  time  00:00:00  on  the  StartDate  and  end  at  24:00:00  on  the  EndDate.  The 
times  must  be  in  consecutive  order,  but  the  difference  between  successive  times  need  not  be 
constant. 


Example: 

WPCfile  ContamW  2.1 
For  WPCtest3.prj 


2 

! flowpaths 

1 

! contaminants 

1 

1 use 

pressure  flag 

0 

! time 

step 

01/01 

! start  date 

01/01 

1 end 

date 

Cl 

! nr 

X 

Y 

Z 

1 

0 . 000 

4 . 000 

1 . 500 

2 

8 . 000 

4 . 000 

1 . 500 

01/01 

00:00: 

00  101325 

1 .204 

101308 .30 

101306 

.30 

o 

o 

1 . Oe-6 

01/01 

24:00: 

00  101325  1.2041 

101308 .30 

101306 

.30 

o 

o 

1 . 5e- 6 

map 

0 

0 


2.4.10  Path  Location  Data  File  (.PLD) 

The  PLD  (Path  Location  Data)  File  will  consist  of  the  locations  of  any  flow  paths  that  connect 
the  building  to  the  external  environment,  as  well  as  additional  information  for  directing  the 
behavior  of  the  EWC  File  Converter.  This  file  is  created  by  ContamW  and  stored  in  the  same 
directory  as  the  project  file  having  the  same  name  as  the  project  file  but  with  the  .pld  extension 
replacing  the  .prj  extension.  It  is  created  as  needed  for  use  in  comparing  WPC  file  information 
with  that  in  the  CONTAM  project  file,  (see  Working  with  WPC  Files  in  Part  1 of  this  document). 

• The  file  is  in  an  ASCII  line-delimited  format. 

• The  reference  location,  defined  by  (Xref,Yref,Zref),  represents  the  EWC  file  location  that  is 
equivalent  to  the  origin  of  the  CONTAM  coordinate  system  for  the  path  locations.  The  user 
must  coordinate  between  the  EWC  file  and  CONTAM  file  to  determine  this  location's 
coordinate  values. 
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• The  rotation  angle  is  about  the  Z (vertical)  axis.  The  user  must  coordinate  the  direction  of 
rotation  between  CONTAM  and  EWC  file  coordinates  It  is  assumed  there  are  no  rotations 
about  the  X or  Y axes. 

• The  six  coordinates  on  line  6 define  a bounding  box  that  surrounds  the  flow  paths  within  this 
file,  which  could  be  used  to  assist  the  EWC  File  Converter  in  rapidly  excluding  unneeded 
points  (e.g.,  that  are  too  distant  from  the  building)  during  the  mapping  process.  Note  that  this 
bounding  box  does  not  necessarily  surround  the  entire  building. 

• The  simulation  time  step  provides  a recommendation  to  the  EWC  File  Converter  for  reducing 
the  size  of  the  WPC  file,  so  that  only  the  time  steps  that  coincide  with  the  simulation  time 
step  could  be  included  (which  could  reduce  interpolation  required). 

• Each  flow  path  is  uniquely  identified  by  a combination  of  flow  path  type  and  flow  path  ID 
values. 

• Comments  begin  with  an  exclamation  point  (T)  and  may  begin  at  the  start  of  any  line  (so 
that  the  entire  line  will  be  ignored)  or  after  all  fields  of  a line  (so  that  the  remainder  of  the 
line  will  be  ignored). 

• For  user  readability,  fields  should  be  commented  whenever  possible. 

• The  Precision  column  for  the  real  data  types  may  be  interpreted  similar  to  a C scanf() 
statement's  conversion  specification. 

HEADER  SECTION: 


Line 

Field 

Data  Type 

Precision 

Notes 

1 

EWC  filename 

character 

filename  includes  full  path 

? 

WPC  filename 

character 

filename  includes  full  path 

3 

file  comments 

character 

User-defined  notes  about  this  file 

4 

coordinate  headings 

character 

this  is  one  line  of  comments  for  the  next  section: 

set  to  “IXref  Yref  Zref  angle" 

5 

Xref 

real 

%7.3f 

units  of  meters 

5 

Yref 

real 

%7.3f 

units  of  meters 

5 

Zref 

real 

%7.3f 

units  of  meters 

5 

rotation  angle 

real 

%8.3f 

rotation  about  Z axis  in  degrees; 

positive  for  CCW  direction 

6 

latitude 

real 

%8.4f 

units  of  degrees;  sign  is  positive  for  north 

6 

longitude 

real 

%8.4f 

units  of  degrees;  sign  is  positive  for  east 

7 

bounding  box  headings 

character 

this  is  one  line  of  comments  for  the  next  section: 

set  to  “!Xmin  Xmax  Ymin  Ymax  Zmin  Zmax" 

8 

Xmin 

real 

%7.3f 

units  of  meters 

8 

Xmax 

real 

%7.3f 

units  of  meters 

8 

Ymin 

real 

%7.3f 

units  of  meters 

8 

Ymax 

real 

%7.3f 

units  of  meters 

8 

Zmin 

real 

%7.3f 

units  of  meters 

8 

Zmax 

real 

%7.3f 

units  of  meters 
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9 time  step  headings 

character 

this  is  one  line  of  comments  for  the  next  section: 

set  to  ”!step  shift  start  end" 

10  time  step 

integer 

units  of  seconds 

10  data  shift 

time 

format  of  hh:mm:ss;  this  is  the  starting  time  for 

the  EWC  time  steps  when  converted  to  WPC 

1 0 start  date 

date 

fonnat  of  mm/dd 

10  end  date 

date 

format  of  mm/dd 

1 1 wind  pressures 

integer 

1:  include  pressures  in  WPC;  0:  don't 

1 1 number  of  species 

integer 

1 1 species  map  tolerance 

real 

%7.3f 

for  use  by  EWC  file  converter  file  to 
match  species  between  EWC  and  PLD  files  by 
molecular  weight. 

CONTAMINANT  DEFINITION  SECTION: 

12  species  headings 

character 

this  is  one  line  of  comments  for  the  next  section: 
set  to  “Iname  m.wt" 

The  next  (number  of  species)  lines  contain  this  data: 

for  each  species... 

name 

character 

molecular  weight 

real 

%6.2f 

end  for  each  species 

FLOWPATH  DEFINITION  SECTION: 

number  of  flow  paths 

integer 

path  map  tolerance 

real 

%7.3f 

for  use  by  EWC  file  converter  to  match  flow  paths 
that  are  more  than  this  distance  away:  units  of  meters: 
this  field  is  on  the  same  line  as  the  above  field 

flow'  path  headings 

character 

this  is  one  line  of  comments  for  the  next  section: 
set  to  “!type  ID  X Y Z" 

The  next  (number  of  flow'  paths)  lines  contain  this  data: 

for  each  flow  path... 

flow  path  ID  number 

integer 

X 

real 

%7.3f 

units  of  meters 

y 

real 

%7.3f 

units  of  meters 

z 

real 

%7.3f 

units  of  meters 

end  for  each  flow  path 

last  line  marker  -999 

integer 

Example: 

C:\Program  Files\Contamw2\Pr j s\WPCcube . ewe  ! EWC  file 
C:\Program  Files\Contamw2\Pr j s\WPCcubel . wpc  ! WPC  file 
WPC  description 
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Xref 

Xref 

Yref 

angle 

0 . 000 

0 . 000 

0 . 000 

0 . 00 

0 . oooc 

) 0.0000 

! no  latitude/longitude 

Xmin 

Xmax 

Ymin 

Ymax  Zmin 

Zmax 

0 . 000 

5 . 000 

2 . 500 

10.000  1.000 

1 . 000 

step 

shift 

start 

end 

0 

00:00:  00 

1/1 

1/1 

1 

2 

0.01  ! 

pressures  flag,  # 

species,  mapping 

name 

CO 

C02 

4 

m . wt 

28 . 00 

44 . 00 

1.00  ! number  of 

flow  paths  and  mapping  tolerance 

id# 

X 

Y 

Z 

1 

5 . 000 

10 . 000 

1 . 000 

2 

0 . 000 

7 . 500 

1 . 000 

3 

0 . 000 

5 . 000 

1 . 000 

4 

0 . 000 

2 . 500 

1 . 000 

-999 


tolerence 


2.4.11  ContamX  Log  File  (CONTAMX2.LOG) 

ContamX  produces  a “log  file'’  summarizing  its  execution  every  time  it  is  run.  The  log  file  was 
created  primarily  as  an  aid  to  the  program  developers,  but  it  can  also  help  the  user  to  more 
effectively  run  the  program.  In  particular,  it  can  be  used  to  optimize  the  performance  of  a 
particular  simulation,  and  it  records  error  messages  to  help  the  user  or  the  program  developers 
track  down  problems. 

The  log  file  is  named  CONTAMX2.LOG  and  is  written  into  the  directory  containing 
CONTAMX2.EXE.  It  is  therefore  overwritten  every  time  ContamX  is  run.  This  prevents  an 
accumulation  of  such  files  but  requires  the  user  to  review  the  file  before  a subsequent  run 
replaces  it. 

The  following  example  output  is  from  a very  large  project  (1.4  Mbytes)  involving  a steady-state 
calculation  with  489  zones  and  4246  duct  junctions. 

Program:  C:\ContamW2\ContamX2.exe  : Thu  Jan  02  10:33:02  2003 

Project:  C:\ContamW2\PrjFiles\ManyDucts.prj  : Thu  Jan  02  10:16:04  2003 

Time:  Thu  Jan  02  13:19:28  2003 

The  first  three  lines  of  the  log  file  report  the  full  path\name  of  the  program  and  the  time  it  was 
created,  the  full  path\name  of  the  project  file  and  the  time  it  was  created,  and  the  time  the 
program  started  running. 

Reading  project  file:  C:\Program  Files\ContamX2 \ test . pr j 
Read  PRJ  : 3391868  bytes  allocated,  1082748  freed,  2309120  net 


Number  of  -- 

contaminants:  0 

day  schedules:  0 

week  schedules:  0 

filters : 0 

reactions:  0 

wind  profiles:  0 

source  elements:  0 

flow  elements:  317 


airflow  nodes:  4735 
airflow  paths:  7690 
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source/sinks:  0 

I lie  second  section  of  the  log  file  summarizes  reading  the  project  file.  It  includes  the  total  heap 
memory  allocated,  heap  used  temporarily  and  freed,  and  the  net  heap  remaining  in  use.  It  notes 
the  number  of  components  in  the  simulation  (in  this  case  for  airflows  only).  This  section  can 
.1 1 so  include  an  echo  of  the  project  file  (the  echo  parameter  on  the  first  line  of  the  project  file)  to 
locate  any  error  messages  that  occur  while  reading  the  project  file. 

"t  up  simulation  at:  Thu  Jan  02  13:19:29  2003 
•.if low  Equations: 
t ’34  variable  pressure  nodes 
1 constant  pressure  nodes 
dumber  of  equations:  4735 
Non-zero  elements:  17427 
Initial  fill  fraction:  0.001 
Matrix  Profile  Analysis: 

Average  Profile:  656.94 
Bandwidth:  4229 

Petermining  equation  reordering: 

Equations  will  be  reordered. 

Average  Profile:  204.62 
Bandwidth:  891 
Skyline  Matrix: 

Number  of  rows:  4734 
Lower  Triangle:  968667  elements 
Upper  Triangle:  0 elements 
Fill  fraction:  0.043 

Solve  nonlinear  equations  by  Newton-Raphson  with  variable  trust  region. 

Solve  Jacobian  simultaneous  linear  equations  by  symmetric  skyline  method. 
Arrays:  12080012  bytes  allocated,  1648272  freed,  10431740  net 

I he  third  section  of  the  log  file  summarizes  the  creation  of  the  arrays  for  solving  the  airflow  and 
mass  fraction  equations.  In  this  case  the  skyline  method  with  equation  reordering  (the  default)  is 
being  used  to  solve  the  4734  simultaneous  non-linear  airflow  equations.  Equation  reordering 
reduces  the  average  profile  by  a factor  of  three  resulting  in  a symmetric  matrix  containing 
%8,667  elements.  This  is  most  of  the  additional  heap  allocation. 

Begin  simulation  at:  Thu  Jan  02  13:19:29  2003 

Start:  12110772  bytes  allocated,  1679032  freed,  10431740  net 

Running  steady-state  initialization: 

DATE:  JanOl  time:  00:00:00 

The  fourth  section  echoes  varying  amounts  of  information  during  the  simulation.  It  can  echo  the 
weather,  contaminant,  and  other  input  files  based  on  the  echo  parameter  in  the  project  file.  It  can 
also  record  the  progress  of  a transient  simulation  and  record  the  values  being  written  to  the 
simulation  results  file,  based  on  the  value  entered  for  the  “list"  parameter  which  is  toward  the 
end  of  the  run  control  section  of  the  project  file. 

Time  to  perform  simulation:  123.86  s 

0 time  steps 

1 calls  to  SolveAf ( ) 

31  calls  to  FillAfO 

22  calls  to  luf_sky_s ( ) 

22  calls  to  lus_sky_s ( ) 
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2676  calls  to  cubic (N) 

f acBins : 0000000000000000000001 
rangeDWC : 10062  lam,  2459  trns,  141529  turbulent 

End:  12110772  bytes  allocated,  1679032  freed,  10431740  net 
Final:  12110772  bytes  allocated,  12110772  freed,  0 net 
Time:  Thu  Jan  02  13:21:33  2003 

The  final  section  summarizes  the  calculations,  the  simulation  time,  and  heap  usage.  The 
simulation  time  is  accurate  to  1 /20th  second,  but  may  include  other  programs  operating  under  MS 
Windows.  There  is  one  call  to  solve  the  airflows  which  required  22  iterations  solving  the 
simultaneous  linear  equations.  The  program  frees  all  allocated  heap  memory  as  indicated  in  the 
next  to  last  line  where  the  number  of  bytes  freed  is  identical  to  that  allocated.  The  last  line  is  the 
time  at  which  the  program  terminated.  Subtracting  the  time  when  the  program  started  gives  125 
seconds  total  run  time.  All  but  about  one  second  was  spent  solving  the  airflow  equations. 

2.4. 11.1  Error  Messages 

The  log  file  records  all  error  messages  displayed  on  the  screen.  They  are  of  the  form: 

severity  ( file,  line  ) 
message 

where 

severity  is  a word  describing  the  importance  of  the  error, 

file  is  the  name  of  the  C source  file  where  the  error  message  originates, 

line  is  the  number  of  the  line  in  that  file,  and 

message  describes  the  error  to  the  user. 

2.4.11.2  Evaluation  of  Alternate  Solution  Methods 

ContamX  provides  alternate  methods  to  solve  the  simultaneous  non-linear  equations  and  the 
simultaneous  linear  equations.  These  alternatives  can  be  used  when  a problem  is  encountered 
with  the  default  methods,  and  they  may  provide  better  performance.  Here  we  will  try  several  of 
these  methods,  on  the  same  large  project  presented  previously,  as  an  exploration  of  their 
performance  and  the  use  of  the  log  file  to  improve  performance.  First  we  will  use  the  simple 
under  relaxation  method  to  solve  the  simultaneous  non-linear  equations.  The  simulation 
summary  indicates: 

Time  to  perform  simulation:  107.10  s 
1 calls  to  SolveAf ( ) 

20  calls  to  FillAfO 
19  calls  to  luf_sky_s ( ) 

19  calls  to  lus_sky_s ( ) 

This  is  a small  (13.5%)  improvement  because  there  are  3 (15%)  fewer  N-R  iterations.  The 
simple  trust  region  is  still  recommended  as  being  generally  more  reliable. 

The  default  method  for  solving  the  simultaneous  linear  equations  includes  reordering  the 
equations  to  reduce  the  profile  of  the  Jacobian  matrix.  The  following  results  show  the  impact  of 
not  reordering  the  equations. 
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Skyline  Matrix: 

Number  of  rows:  4734 
Lower  Triangle:  3109960  elements 
Upper  Triangle:  0 elements 
Fill  fraction:  0.139 

Arrays:  28843652  bytes  allocated,  1281568  freed,  27562084  net 

Time  to  perform  simulation:  1394.17  s 
1 calls  to  SolveAfO 

31  calls  to  FillAf() 

22  calls  to  luf_sky_s ( ) 

22  calls  to  lus_sky_s ( ) 

Final:  28874412  bytes  allocated,  28874412  freed,  0 net 

The  number  of  values  stored  in  the  Jacobian  has  more  than  tripled  (970,000  to  3,100,000), 
allocated  memory  has  increased  by  about  1 7,000,000  bytes,  and  - most  importantly  - the 
simulation  time  is  1 1.3  times  longer.  The  gains  will  not  be  as  dramatic  for  smaller  problems  and 
for  those  with  well-banded  Jacobians  as  can  arise  from  tall  buildings.  However,  the  time  for 
reordering  is  so  small,  that  it  should  almost  always  be  tried.  The  reordering  algorithm  is  not 
totally  reliable  - sometimes  it  fails  and  a few  crashes  have  been  observed. 

The  alternate  method  for  solving  the  simultaneous  linear  equations  is  a preconditioned 
conjugate-gradient  (PCG)  algorithm.  This  is  an  iterative  method  (the  skyline  method  is  direct) 
and  may  not  converge.  The  following  results  were  achieved  for  this  case: 

Arrays:  4470060  bytes  allocated,  1281568  freed,  3188492  net 

Time  to  perform  simulation:  74.92  s 
1 calls  to  SolveAfO 

32  calls  to  FillAfO 

23  calls  to  sa_pcg ( ) 

16666  sa_pcg ( ) iterations 

End:  4500820  bytes  allocated,  1312328  freed,  3188492  net 

There  is  a fairly  significant  (39.5%)  improvement  in  solution  time  over  the  default  case.  There  is 
a more  dramatic  savings  (69%)  in  net  allocated  memory.  The  PCG  method  always  uses  less 
allocated  memory  than  the  skyline  method,  although  that  is  usually  not  a problem  - especially 
for  relatively  small  projects.  The  PCG  method  is  also  usually  slower  than  skyline  for  small 
projects.  The  PCG  method  should  be  tested  when  you  have  a large  problem  that  will  require 
several  runs  for  a full  analysis. 

2.4.12  ContamW  Configuration  File  (CONTAM.CFG) 

Each  time  ContamW  is  run,  it  checks  for  the  existence  of  the  contain. cfg  file.  This  file  contains 
the  default  settings  to  use  when  the  program  is  run  (see  Configuring  CONTAMW  in  the  2.0  User 
Manual).  All  of  the  parameters  that  appear  in  the  configuration  file  can  be  modified  using  the 
Options...  selection  of  the  View  menu  except  for  the  EWC-to-WPC  file  converter.  The  value 
saved  will  be  that  which  you  have  set  in  the  WPC  File...  selection  of  the  Weather  menu.  To  reset 
the  converter  name  back  to  “null,”  you  must  edit  the  configuration  file  manually. 

The  first  line  of  the  file  is  used  to  identify 7 the  type  of  file.  It  is  exactly: 

ConfigFile  ContamW  2.1  ! file  type  identification 
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l he  next  five  lines  are  comments  explaining  font  selection. 

/ he  seventh  line  is  the  list  of font  sizes  to  be  made  available  for  zooming  the  SketchPad 

nts  //  number  of  fonts  available  (1-7) 

followed  by  nfont  values  of  font  sizes  (allowed  values  are  1,  2,  3,  4,  5,  8,  16) 

font(l)  ...  font(nfonts) 

/he  next  line  indicates  the  default  set  of  units  to  use  (SI  or  IP) 

■ rUnits  //  default  units  (0,  1)  (14) 

/ he  next  line  indicates  the  default  flow  units  to  use 

:■  uFlowUnit  //  default  flow  units  (0  - 8)  (14) 

/ he  next  line  indicates  the  default  zone  temperature  and  units 

: ief  //  default  zone  temperature  (R4) 

I :nits  //  temperature  units  (0  - 3)  (14) 

1 he  last  line  indicates  the  file  path  of  an  EWC-to-WPC  file  converter  set  to  “ null ” if  not  used 

.will  //  full  pathname  of  file  converter 


Example: 

’onfigFile  ContamW  2.1  ! file  type  identification 

. anything  after  an  exclamation  mark  is  treated  as  a comment. 

. number  of  fonts,  N,  followed  by  N valid  font  sizes  in  increasing  order. 

! 7 123458  16  ! all  valid  sizes;  size  8 is  required. 

: 6 1 2 3 5 8 16  -or-  5 1 2 4 8 16  are  good  choices. 

: if  the  size  1 font  crashes  the  program,  remove  it. 

7 123458  16  ! selected  fonts. 

0 ! default  units:  0 = SI,  1 = IP. 

4 ! default  flow  units:  0 = kg/s,  1 = scfm,  2 = sL/s,  3 = sm3/s, 

! 4 = sm3/h,  5 = lb/s,  6 = sft3/h,  7 = sL/min,  8 = kg/h. 

20  2 ! default  zone  temperatures  in  units: 

I 0 = K,  1 = R,  2 = C,  3 = F. 
null  ! EWC  to  WPC  converter 

2.5  Data  Structures 

Most  of  the  data  structures  are  defined  in  the  files  simdat.h  and  selmts.h.  Global  variables  are 
defined  in  the  sglob.h  and  sxtrn.h  files.  Such  variables  are  indicated  by  a leading  underscore  in 
the  variable  name.  Linked  lists  are  used  extensively  to  store  the  data  describing  the  building 
airflow  and  contaminant  components.  Vectors  and  arrays  are  used  in  the  solution  of  the  linear 
and  nonlinear  equations. 
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PART  3 - ContamW  Program  Documentation 

3.1  Introduction 

This  part  presents  an  overview  of  the  program  structure,  data  and  logic  of  the  ContamW, 
CONTAM's  graphical  user  interface  (GUI).  It  does  not  present  the  functions  in  as  much  detail  as 
was  done  for  the  solver,  because  of  the  large  number  of  files  and  functions  associated  with  the 
GUI.  The  intent  is  to  present  enough  information  to  provide  the  user  of  this  document  with  a 
starting  point  to  understanding  the  program  structure.  The  GUI  provides  a means  of  creating  and 
viewing  the  multi-zone  model,  and  creates  the  PRJ  file  for  use  by  CONTAM's  simulation 
engine,  ContamX.  The  GUI  also  serves  as  a means  to  view  the  simulation  results  that  are  output 
by  ContamX. 

3.2  Development  Environment 

ContamW  is  an  event-driven  program  developed  solely  for  the  Windows  platform  using  the 
WIN32  Application  Programming  Interface  (API)  and  written  in  the  C programming  language. 
Version  2. 1 was  developed  using  Microsoft  Visual  C++  versions  6.0  and  .NET.  As  of  the  release 
of  this  document,  the  source  code  consists  of  87  c-code  files  (.c),  33  header  files  (.h),  8 context- 
sensitive  help  header  files  (.hh),  and  16  resource-related  files.  The  graphical  charting  routines 
were  developed  using  a third-party  charting  tool  OlectraChart  6.0.  This  software  is  required  in 
order  to  build  the  Visual  Studio  project. 

3.3  Program  Structure 

The  figure  below  shows  the  GUI  which  is  made  up  of  two  windows  - one  “superimposed"  on 
top  of  another.  The  SketchPad  window  is  the  large  white  portion  that  is  “superimposed"  on  the 
larger  Main  window. 


Titli 


Tc 


Figure  - The  CONTAMW  GUI 
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3.3.1  Main  Program  and  Message  Loop 

Every  Windows  program  must  have  a WinMainQ  function  which  is  the  entry  point  of  the 
program.  This  function  is  equivalent  to  the  main()  function  in  a standard  C program.  In 
ContamW,  this  function  is  located  in  the  file  contam.c.  WinMainQ  performs  program 
initialization  and  executes  the  main  message  loop  of  the  program. 

As  this  is  an  event-driven  program,  it  contains  a message  loop  that  gets  and  dispatches  messages 
from  and  to  the  operating  system  respectively.  This  loop  gets  messages  that  are  directed  to  the 
ContamW  program  from  the  Windows  message  queue  then  dispatches  the  message  back  to  the 
operating  system  which  then  calls  the  appropriate  window  procedure  of  ContamW  for 
processing. 

3.3.2  Window  Procedures 

Each  window  displayed  by  ContamW,  including  dialog  boxes  and  property  sheet  pages,  has  an 
associated  window  procedure.  Window  procedures  are  called  by  Windows  after  ContamW 
dispatches  messages  associated  with  a particular  window  back  to  the  operating  system.  These 
messages  contain  parameters  that  indicate  to  the  operating  system  which  window  procedure  to 
call,  a message  identifier,  and  message-specific  parameters  as  required.  Window  procedures 
contain  sections  of  code  known  as  message  handlers  that  are  executed  when  the  window 
procedure  receives  a particular  message. 

ContamW  contains  approximately  90  window  procedures.  Two  of  these  procedures,  WndProcQ 
and  SketchPadWndProcQ , are  associated  with  the  two  main  windows  of  the  program  and  the 
remaining  procedures  are  associated  with  individual  dialog  boxes,  property  sheet  pages  and 
miscellaneous  windows  that  display  charts  and  simulation  results.  WndProcQ  handles  the  menu 
and  associated  toolbar  commands  and  passes  keyboard  messages  to  the  SketchPad  window 
procedure  SketchPadWndProcQ.  SketchPadWndProcQ  handles  all  SketchPad  related  commands 
including  drawing  walls,  ducts  and  controls  and  placing  icons  onto  the  SketchPad. 

3.4  Program  Data 

Before  describing  the  ContamW  data  structures,  it  is  important  to  understand  the  basic 
philosophy  of  the  program.  ContamW  is  not  meant  to  depict  an  exact  physical  representation  of  a 
building,  but  to  portray  a building  in  a manner  that  is  representative  of  the  multizone  modeling 
perspective.  Therefore,  the  physical  dimensions  of  the  representations  of  building  zones  are  not 
important,  but  the  interconnectivity  or  topology  of  the  zones  is  important.  The  ContamW 
SketchPad  provides  a means  of  describing  a building  in  a manner  that  constrains  the 
representation  to  the  multizone  modeling  domain. 

3.4.1  SketchPad  Data 

From  the  users  perspective,  the  SketchPad  consists  of  a two-dimensional  grid  of  equal-sized  cells 
in  which  icons  can  be  placed.  The  SketchPad  is  actually  represented  as  a set  of  global  2D  arrays 
having  equal  dimensions  indicating  the  width  (columns)  and  height  (rows)  of  the  SketchPad. 
These  arrays  are  used  to  indicate  the  symbols  located  on  the  SketchPad  for  each  building  level 
and  to  maintain  references  to  lists  of  data  elements  that  contain  the  detailed  information 
describing  the  building  elements  that  make  up  each  building  level.  The  following  is  a list  of  the 
SketchPad  arrays  along  with  a description  of  the  values  stored  in  each  array.  Values  are  defined 
in  contain. h.  In  the  list  below,  the  first  array  in  each  set  contains  information  related  to  the 
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building  level  currently  displayed  on  the  SketchPad,  and  the  second  (preceded  by  _SL)  contains 


information  related  to  the 

evel  below  the  current  level,  i.e.  the  sublevel. 

Sketch [row] [col] 

SLSketch [row]  [col] 

Contains  identifiers  indicating  a symbol  for 

Zones,  Flow  path,  Simple  AHS , Supply,  Return, 

Note,  Source  Sink  and  Exposure  (o  =>  empty  cell) 

Walls  [row]  [col] 

SLWalls [row]  [col] 

Contains  identifiers  indicating  the  wall  symbol. 
Symbol  values  from  WL  EW  to  WL  NESW. 

Zones  [row]  [col] 

SLZones [row]  [col] 

Indicates  zone  number  for  every  cell  on  the 
SketchPad . 

AMBT  32766  =>  ambient  zone 

ZNDF  -2  =>  undefined  zone 

WALL  32767  =>  wall  location 

Paths [row] [col] 

SLPaths [row] [col] 

Contains  the  id  number  of  each  symbol  that 
represents  a building  component.  The  following 
types  of  components  warrant  values  in  the  Paths 
array:  Airflow  paths,  Ducts,  Junctions , Zones  and 
Notes . 

Ducts  [row]  [col] 

SLDucts [row] [col] 

Contains  identifiers  indicating  a symbol  for  all 
Ducts,  Junctions  and  Terminals . Values  are  from 
DCT_EW  to  IOJ_CB. 

Links  [row]  [col] 

SLLinks [row]  [col] 

Contains  identifiers  indicating  controls-related 
symbols.  Values  are  from  CL  EW  to  CTRL  P. 

Ctrls  [row]  [col] 

SLCtrls [row] [col] 

Contains  a ctrl/link  number  for  each  control 
symbol  in  the  corresponding  Links  array. 

Table  - Global  SketchPad  arrays 

An  example  of  a project  file  and  associated  SketchPad  arrays  is  presented  in  spreadsheet  form  in 
Appendix  3A  at  the  end  of  this  section. 
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3.4.2  Building  Organization 

ContamW  buildings  (projects)  are  organized  by  building  levels  that  contain  building  component 
information.  This  organization  is  represented  by  a doubly  linked  list  of  level  data  structures 
( LEV  DATA ) as  illustrated  in  the  figure  below.  This  list  is  used  to  populate  the  SketchPad  arrays 
whenever  the  user  selects  a different  level  to  display.  A global  pointer  is  used  to  access  the 
current  level  and  the  levels  above  and  below  the  current  level  are  accessed  via  each  level's 
pointer  to  the  level  above  and  below.  Each  level  contains  a pointer  to  a list  of  icon  data  for  all  of 
the  icons  contained  on  the  level.  Icon  data  structures  (ICON  DAT)  contain  information  that 
includes  the  component  number,  icon  identifier,  and  column  and  row  in  which  the  icon  is  located 
on  the  SketchPad,  i.e.,  in  the  SketchPad  arrays. 

LevO 


LEV  DATA  LEV  DATA  LEV  DATA 


Figure  - Schematic  of  Building  Level  and  Icon  Data  Storage 


3.4.3  Building  Component  and  Element  Data 

The  data  used  to  describe  a building  in  ContamW  is  basically  divided  into  two  types:  building 
component  and  building  element  data.  In  terms  of  how  the  data  is  managed  by  ContamW  - these 
data  are  referenced-by-number  (RefByNum)  and  referenced-by-name  (RefByName) 
respectively.  RefByName  data  are  referenced  by  a unique,  user-defined  name,  and  RefByNum 
data  are  referenced  by  a number  assigned  by  ContamW. 

RefByNum  data  are  those  that  are  considered  specific  to  a building  (project)  and  include  zones ; 
airflow  paths ; simple  air  handling  systems ; duct  segments  Junctions  and  terminals ; source-sinks ; 
occupants  and  controls.  These  components  only  exist  in  relation  to  a given  building,  i.e.,  they 
physically  relate  to  other  components  of  the  building  and  are  represented  on  the  SketchPad  by 
individual  icons.  RefByName  data  are  those  types  of  data  that  can  be  shared  between  building 
components  and  even  between  different  projects  via  ContamW  libraries.  RefByName  elements 
include  airflow  elements , duct  flow  elements , wind  pressure  profiles , species , source-sink 
elements  .filter  elements , kinetic  reaction  elements , non-occupant  schedules  and  annotations. 

RefByNum  data  can  refer  to  RefByName  data,  and  more  than  one  RefByNum  component  can 
refer  to  the  same  RefByName  element.  For  example  an  airflow  path  (e.g.  a doorway)  connects 
two  zones  of  a building  is  defined  in  part  by  its  location  within  the  building.  The  airflow 
characteristics  of  this  airflow  path  are  represented  by  a pressure-flow  model  characterized  by  an 
airflow  element.  There  may  be  several  doors  having  the  same  airflow  characteristics;  therefore, 
each  airflow  path  (e.g.  door)  can  refer  to  the  same  airflow  element. 

Building  component  data  are  stored  in  linked-lists  as  shown  in  the  figure  below  that  illustrates 
the  concept  for  airflow  paths  and  elements.  These  lists  are  referred  to  by  and  accessed  through 
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arrays  of  pointers  (e.g.  PathLisi ) that  are  used  to  maintain  the  components  in  order  according  to 
their  location  within  the  building.  Building  components  are  numbered  starting  at  the  top  level  in 
the  upper  left  hand  comer  of  the  SketchPad  moving  left  to  right  and  down  the  SketchPad  then 
proceeding  down  through  each  level  in  the  same  manner.  Whenever  a project  file  is  saved, 
reordering  of  the  array  of  pointers  and  renumbering  of  the  building  components  will  be 
performed  as  necessary  . 


Figure  - Schematic  of  Airflow  Path  Component  ( PATHDSC ) and 
Element  (AFE  DAT)  Data  Storage 


The  figure  above  shows  some  of  the  global  variables  that  are  used  to  maintain  the  list  of  airflow 
paths  (components)  and  airflow  elements  that  are  referenced  by  the  paths.  _PathList  is  the  array 
of  pointers  used  to  maintain  the  SketchPad  order  of  the  paths.  _PcithsO  is  a pointer  to  the  head  of 
the  linked  list  of  PATHDSC  stmctures.  PathX  is  a pointer  to  the  head  of  a list  of  paths 
structures  that  have  been  deleted,  but  could  be  reused  when  new  paths  are  added. 

The  routines  used  to  create  new  paths  are  contained  in  the  file  paths,  c.  These  routines  are  typical 
of  the  building  component  management  routines: 

□ Path  creation  functions:  pathnewf).  pathjdflt(').  path jaddO.  path _put() 

□ Path  deletion  functions:  path _del(). path  delete f) 

□ Path  editing  functions:  path _ol d() . path _get() 

The  routines  for  managing  airflow  element  related  data  are  found  in  afedlg.c  (airflow  element 
specific)  and  cutils.c  (building  elements  in  general). 

□ Airflow  element  creation  functions:  afelmtjnewf).  elmt  insert!) 

□ Airflow  element  deletion  functions:  elmt  delete!) 

□ Airflow  element  editing  functions:  afelmt_old(),  elmt  replacef) 

These  data  are  managed  by  a set  of  lower  level  routines  that  perform  all  memory 
allocation  deallocation  for  ContamW.  These  routines  are  located  in  the  file  heap.c.  These 
memory  management  routines  are  used  to  minimize  the  number  of  actual  calls  to  the  standard-C 
mcilloct)  and  free!)  functions  by  maintaining  memory  used  by  ContamW  in  larger  memory- 
blocks  with  which  the  routines  in  heap.c  operate. 
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3.5  Program  Logic 

As  previously  indicated,  ContamW  is  an  event-driven  program,  which  basically  means  that  the 
program  functions  that  are  executed  depend  on  user-generated  commands,  i.e.,  user  events. 

These  events  fall  into  the  following  basic  categories:  saving/retrieving  project  files,  drawing 
building  components,  editing  building  components,  running  simulations  and  working  with 
simulation  results.  The  following  sections  describe  the  program  logic  that  handles  these  events. 

3.5.1  Message  (Event)  Handlers 

Selecting  an  item  from  the  menu  or  double-clicking  on  a SketchPad  icon  are  examples  of  events 
for  which  message  handlers  are  required.  In  ContamW,  all  menu  selection  events  are  handled  by 
the  WMCOMMAND  message  handler  WndProc_OnCommand()  of  WndProcQ.  Each  menu 
selection  is  associated  with  a resource  identifier  that  is  used  as  a case  selector  of  a switch 
statement  in  the  WM  COMMAND  message  handler.  For  example,  if  the  user  selects  the  File- 
Open  command,  the  WM  COMMAND  message  is  sent  with  the  identifier  of  the  File-Open  menu 
resource  IDM  FILE  OPEN.  In  the  case  of  a double-click  mouse  event  on  the  SketchPad 
window,  both  the  W ML  BUTTON DOWN  and  WM  LBUTTONDBLCLK  commands  are  sent  to 
SPWndProc _OnLButtonDown()  message  handler  of  SketchPadWndProc(). 

3.5.2  Saving  and  Retrieving  Project  Files 

CONTAM  project  files  are  ASCII  files  that  maintain  all  information  related  to  a CONTAM 
project.  The  project  file  format  is  described  in  detail  in  the  section  Project  File  (,PRJ).  Project 
file  related  commands  are  executed  via  the  File  menu  and  are  handled  within  the 
WM  COMMAND  message  handler  of  the  main  window  procedure  WndProc().  The  File  menu 
identifiers  are  all  of  the  form  IDMFILEX  where  X is  one  of  the  following  NEW , OPEN , 

SA  VE,  SA  VE  AS , or  EXIT.  File  input  (reading)  and  writing  (saving)  are  handled  by  the 
prj  readQ  and  prjsciveQ  functions  contained  in  the  files  prjrecid.c  and  prjsave.c.  These  two 
functions  call  lower  level  functions  each  of  which  handles  a specific  section  of  the  project  file  as 
described  in  the  project  file  documentation. 

There  are  a few  other  features  of  note  related  to  project  file  processing.  If  the  user  attempts  to 
open  a project  file  of  an  older  version,  conversion  functions  will  be  called  to  convert  to  a format 
compatible  with  the  current  version  of  the  program.  These  routines  are  located  in  the  file 
c!0toc20.c.  If  the  user  clicks  the  OK  button  after  viewing  a building  component  data  dialog  box, 
a global  flag  saveprjf  is  set  to  indicate  that  the  file  should  be  saved  and  a warning  will  be 
displayed  if  the  user  attempts  to  exit  the  program  with  this  flag  set.  Also,  the  project  file  will  be 
saved  automatically  when  the  user  attempts  to  perform  a simulation,  because  the  simulation 
program  reads  the  project  file  and  it  is  a separate  executable  from  the  GUI. 

3.5.3  SketchPad  Drawing 

Icons  are  placed  upon  the  SketchPad  using  either  one  of  the  four  drawing  tools  or  the  popup  icon 
placement  menu. 

3. 5. 3.1  Drawing  Tools 

There  are  four  drawing  tools:  line  and  box  for  walls,  ducts  and  control  links.  Tool  selection  is 
performed  via  either  the  Tool  menu  or  associated  toolbar  buttons.  The  message  handlers 
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contained  in  WndProcQ  associated  with  each  tool  set  a global  flag  to  indicate  which  tool  is 
selected:  bWcill , bBox , bDuct  or  bLink. 

The  actual  drawing  process  is  activated  once  the  user  clicks  the  left  mouse  button  (or  hits  the 
Enter  key)  at  which  point  the  drawing  mode  is  activated  and  indicated  by  setting  the  flag 
bDraw.  When  in  the  drawing  mode,  all  mouse  commands  and  keyboard  arrow  key  commands 
are  captured  by  the  SketchPad  window  and  converted  to  the  ContamW-specific  message 
CT  DRAW  handled  by  the  function  SPW ndProc  OnCtDrm  v() . SP  WndProcOnCtDrciwQ  then 
calls  specific  drawing  functions  depending  on  the  selected  drawing  tool  as  indicated  by  the 
drawing  tool  flags.  Drawing  is  finalized  by  clicking  the  left  mouse  button  activating  the  message 
handler  SPWndProc  OnLButtonDownQ . This  message  handler  will  then  call  the  drawing  tool 
dependant  routines  to  validate  the  drawing  and  place  the  proper  icons  into  SketchPad  arrays.  If 
the  drawing  was  valid  then  the  screen  can  be  updated  to  reflect  the  placement  of  the  building 
components,  e.g.,  walls,  ducts  or  control  links.  This  is  performed  via  the  Inva/idateRect() 
command  that  causes  the  SketchPad  window  to  redraw  or  repaint  itself.  SketchPad  *kpainting,,  is 
performed  via  the  WM  PAINT  message  handler  SPWndProc _OnPaint(). 

The  following  is  a pseudo-code  outline  of  the  drawing  process,  and  the  following  list  indicates 
the  functions  and  their  locations  within  the  source  code  files. 
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Select  Tool 

WndProc_OnCommand  ( IDM_TOOLS_DRAWWALL 
{ _bWall  = true; 

SPWndProc_OnCtSwitchCursor ( 1 ); 

} 

Begin  Drawing 

SPWndProc_OnLButtonDown ( ) 

{ if ( !_bDraw  ) _bDraw  = true; 

} 

Drawing 

SPWndProc_OnKey ( left  | right  | up 
SPWndProc_OnMouseMove ( x,  y ) 

{ SendMessage ( SketchPad,  CT_DRAW, 

} 

Finish  Drawing 

SPWndProc_OnLButtonDown ( ) 

{ if ( _bDraw  ) 

if ( wall_check()  ==  0 ) 

{ walls_set ( 0 ) ; 
zones_set ( 0 ) ; 

InvalidateRect ( SketchPad  ) 

} 

} 


User:  selects  drawing  tool 
//  tool  selection  flag 
//  display  drawing  cursor 


//  User:  clicks  LMB 
//  set  drawing  flag 


down  | enter  | esc  ) 
dir,  increment  ) ; 


//  User:  clicks  LMB 

//  validate  wall  drawing 
//  set  icons  in  _Walls  []  [] 
//  set  icons  in  _Zones  []  [] 
//  send  WM_PAINT  message 


Pseudocode  for  the  Wall  Drawing  Process 


II 


SketchPad  Painting  - Display  of  SketchPad  arrays  on  the  screen 


SPWndProc_OnPaint ( ) //  SketchPad  window  WM_PAINT  message  handler 

{ 


sketch_redraw ( ) 

{ f or ( for  each  cell  of  SketchPad  ) 
{ sk_draw_symbol ( ) 

{ grblank ( ) ; 

sk_draw_icon ( ) 

{ grputc(icon,  color) 

{ SetTextColor (color ) ; 
TextOut (icon) ; 


/ / set  background  color  of  icon 
/ / get  icons  from  SketchPad  arrays 

//  Windows  API  function  call 
//  Windows  API  function  call 


TextOutQ 

This  is  a Windows  Graphics  Device  Interface  (GDI)  function  that  outputs  text  to  a given  device 
context  which  in  this  case  is  the  SketchPad  window.  The  fonts  for  the  device  (WALTONOl -1 6.FON) 
are  initialized  at  program  startup  by  the  lnitFont()  function  call  from  within  SPWndProc_OnCreate(). 
The  ContamW  installation  program  installs  these  fonts  into  the  system  fonts  folder. 
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Function 

File  Name 

WndProc_OnCommand(  ) 

I DM  TOOLS  DRAW  WALL 

WndProc.c 

SPWndProc  OnCtSwitchCursor( ) 
SPWndProc_OnLButtonDown(  ) 
SPWndProc  OnKey(  ) 

SPWndProc  OnMouseMove(  ) 
SPWndProc_OnCtDraw(  ) 
SPWndProc  OnPaint(  ) 

SPWndPro.c 

walls_set(  ) 
zones_set(  ) 
sketch_redraw( ) 
sk  draw  symbol() 
sk  draw  icon() 

sketch. c 

wall  check(  ) 

wall  draw,  c 

grblank(  ) 
grputc(  ) 

InitFont(  ) 

wutils.c 

SetTextColor(  ) 

TextOut(  ) 

Windows  API 

Table  - SketchPad  Drawing  Related  Functions 


3. 5.3.2  Icon  Placement 

Some  building  components  are  drawn  onto  the  SketchPad  via  the  pop-up  icon  placement  menu. 
This  menu  contains  a list  of  building  components  that  are  represented  by  specific  icons.  The 
menu  selections  are  enabled/disabled  based  on  context-sensitive  rules  for  icon  placement. 

1 lie  menu  is  activated  when  the  user  clicks  the  right  mouse  button  (RMB)  on  the  SketchPad. 

This  causes  the  WMjONR BUTTON DOWN  message  to  be  sent  to  the  SketchPad  window  which 
is  handled  by  the  SPWndProc  OnRButtonDownt ) message  handler.  This  in  turn  calls  both 
SetPopMenuQ  and  TvackPopMemd)  functions.  SetPopMenuf)  is  a ContamW  function  that 
implements  the  context-sensitive  rules  of  icon  placement,  and  TvackPopMemd ) is  a Windows 
API  function  that  displays  the  actual  menu  wherever  the  mouse  pointer  is  when  the  RMB  is 
clicked.  When  the  user  selects  an  item  from  the  icon  placement  menu  a WM COMMAND 
message  is  sent  to  the  SketchPad  window  along  with  a menu  command  identifier.  The 
SPWndProc  OnCommandO  message  handler  function  contains  a case  for  each  icon  placement 
menu  selection  of  the  form  IDM  POP1  _X  where  X stands  for  ZONE , AMBIENT , PHANTOM , 

PA  TH . AHS , INLET . OUTLET , SS.  EXPOSURE , or  NOTE.  Each  of  these  message  handlers 
places  the  corresponding  icon  identifier  in  the  appropriate  SketchPad  array  then  calls  the 
sk  draw  symbol ()  function  to  display  the  new  icon  on  the  SketchPad  window.  The  icon  will  be 
red  in  color  to  indicate  that  the  icon  is  undefined,  i.e.,  it  is  not  yet  associated  with  a building 
component.  At  this  point  a value  indicating  an  undefined  building  component  will  also  be  placed 
into  the  appropriate  SketchPad  arrays  if  necessary,  e.g.,  a value  of  ZNDF  (-2)  indicating  an 
undefined  zone  will  be  placed  in  the  Paths  array  and  in  every  cell  of  the  Zones  array  that  is 
enclosed  by  the  walls  immediately  surrounding  the  zone  icon. 
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3.5.4  Creating  and  Editing  Building  Components 

Once  an  icon  is  placed  on  the  SketchPad  a building  component  must  be  created  and  associated 
with  it.  This  is  done  via  dialog  boxes  and  property  sheets  associated  with  the  type  of  building 
component  represented  by  the  particular  icon. 

When  the  user  double  clicks  on  an  undefined  icon  on  the  SketchPad  the  WMLBUTTONDOWN 
message  is  sent  to  the  SketchPad  window  with  the  fDoubleClick  parameter  set  to  true.  The 
SPWndProcOnLButtonDownQ  function  checks  the  SketchPad  arrays  in  a hierarchical  fashion  to 
determine  the  type  of  icon  for  which  to  display  properties.  Having  determined  the  type  of 
undefined  icon,  a temporary  building  component  data  structure  is  allocated  with  default  values. 
This  temporary  structure  is  passed  as  a parameter  to  the  associated  component  dialog  box 
procedure  (a  type  of  window  procedure)  to  be  modified  as  required  by  the  user.  If  the  user  selects 
‘"OK"  on  the  dialog  box,  control  returns  to  the  SPWndProcOnLButtonDownQ  message  handler, 
and  a permanent  copy  of  the  data  structure  representing  the  building  component  is  made  and 
added  to  the  corresponding  list  of  building  components  (see  Building  Component  and  Element 
Data).  At  this  point  a number  value  is  assigned  to  the  building  component  by  ContamW  and 
placed  into  the  appropriate  SketchPad  array  at  the  proper  location. 

Editing  of  existing  building  components  is  accomplished  in  much  the  same  way  as  creating  a 
new  one.  The  user  double  clicks  on  the  desired  icon  and  instead  of  creating  a new,  default 
component,  a copy  is  made  of  the  existing  component  and  sent  to  the  appropriate  dialog  box 
procedure. 

3.5.5  Running  Simulations 

ContamW  is  used  to  develop  a set  of  equations  that  represents  a building  as  a multizone  airflow 
and  contaminant  transport  network.  The  GUI  provides  the  means  to  develop  a schematic 
representation  of  the  building  in  the  level  of  detail  required  by  the  multizone  modeling  paradigm. 
The  equation  solver  then  takes  this  schematic  representation  and  converts  it  into  a set  of  airflow 
and  contaminant  transport  equations. 

The  equation  solver,  contamx2.exe , is  a stand-alone  executable  that  operates  directly  on  the 
project  file  created  using  the  ContamW  GUI.  Simulation  parameters  are  input  by  the  user  via  the 
Simulation  Parameters  property  sheet  accessed  from  the  Simulation->Set  Simulation  Parameters 
menu  command.  A simulation  is  run  when  the  user  selects  Simulation->Run  from  the  menu 
which  causes  the  I DM  SIMULATION  RUN  case  of  the  WndProcOnCommandQ  message 
handler  function  to  be  executed  which  calls  the  function  ContamSimQ  located  in  the  source  file 
SimDIgX2.c.  ContamSimQ  uses  the  CreateProcessQ  Windows  API  function  to  execute 
contamx2.exe  in  another  thread.  Complete  documentation  of  the  solver  is  provided  in  Part  2 - 
ContamX  Program  Documentation. 

3.5.6  Viewing  Simulation  Results 

The  equation  solver  creates  an  output  file  having  the  same  name  as  the  project  file  but  with  the 
.sim  extension.  The  GUI  can  be  used  to  display  these  results.  Results  can  also  be  exported  to  tab- 
delimited  text  files  for  importing  into  spreadsheet  programs  for  more  detailed  analysis  or  written 
to  report  files  that  are  organized  for  legibility.  There  are  several  methods  of  viewing  results  via 
the  GUI  as  described  below. 
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3. 5. 6. 1 SketchPad  Results 

SketchPad  results  - in  the  form  of  color-coded  lines  to  indicate  the  relative  magnitude  and 
direction  of  pressure  drop  and  airflow  rate  - can  be  displayed  for  each  airflow  path  one  level  and 
one  time  step  at  a time  (See  figure  below).  If  a matching  .sim  file  is  available,  a global  variable 
_resready  is  set  to  true,  and  the  user  can  select  to  view/hide  the  results  display  and  select 
different  time  steps  of  transient  results  to  display  via  the  set  of  View  menu  commands  which  are 
handled  by  the  IDM_VIEW_X  cases  of  the  function  WndProc_OnCommand().  The  SketchPad 
results  are  read  from  the  .sim  file  by  the  age_of_air()  function  for  the  current  time  step  as 
maintained  in  the  global  variable  _time_index.  The  actual  display  of  results  is  handled  within  the 
SPWndProcjOnPaintQ  message  handler  function  which  calls  res_dsp_level()  that  performs 
scaling  of  the  lines  and  calls  lower  level  display  functions  grlinevwf)  and  grlinehwQ  that  in  turn 
call  Windows  GDI  functions  to  perform  the  actual  graphical  display.  Along  with  the  color-coded 
lines,  the  value  and  direction  of  the  airflows  and  pressure  drop  of  the  individual  airflow  paths  are 
displayed  in  the  status  bar  for  the  currently  highlighted  airflow  path  icon  on  the  SketchPad.  This 
is  done  via  the  sketch _status()  function  which  is  called  when  several  events  occur  including 
change  of  highlighted  SketchPad  cell  via  keyboard  or  mouse  movement,  changing  the  current 
level  displayed  or  changing  between  SketchPad  display  modes  (normal,  results,  wind  and  links). 


(CONTAMW2  - TeslCtrlJJLS  pij 
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Figure  - SketchPad  Displaying  Simulation  Results  of  Airflow  (blue  lines)  and  Pressure 

Difference  (red  lines)  for  Airflow  Paths 
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Function 

File  Name 

WndProc  OnCommand( ) 
IDMVTEWX 

WndProc. c 

SPWndProc  OnPaint( ) 

SPWndPro.c 

age_of_air() 

flowsout.c 

res_dsp_level( ) 

resultsw.c 

grlinevw( ) 

grlinehw( ) 

wutils.c 

sketch_status( ) 

bsketch.c 

Table  -SketchPad  Results  Display  Functions 


3. 5. 6. 2 Results  Display  Window 

Users  may  choose  to  display/hide  a separate  results  display  window  (shown  in  the  right  side  of 
the  figure  below).  This  window  displays  contaminant  concentrations  results  and  net  airflow  rates 
between  adjacent  zones  of  the  currently  highlighted  zone  icon  on  the  SketchPad  for  steady  state 
simulations  and  for  the  current  display  time  step  for  transient  simulations.  Occupant  related 
results  can  also  be  displayed  in  this  window  for  highlighted  exposure  icons.  This  window  is  a 
modeless  dialog  box  for  which  a global  handle  ghDlgResults  is  maintained  to  which  messages 
are  dispatched  from  the  main  message  loop.  The  dialog  box  procedure  for  this  window 
SSResultsDlgProc()  is  located  in  the  file  SSResDlg.c.  This  window  is  updated  when  appropriate 
by  sketch  statusQ  which  sends  messages  to  this  window  via  the  g hDlgResults  handle. 
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3. 5. 6. 3 Result  Graphs 

Users  can  use  the  GUI  to  display  graphs  of  transient  simulation  results  (see  figure  below)  via  the 
Simulation->Plot. . . menu  commands.  These  commands  are  handled  by  the 
IDM_SIMULATION  GRAPH X cases  of  the  WndProc_OnCommand(),  where  X is  either 
CONTAM,  AIRFLOW  or  EXPOSURE.  Each  of  these  cases  will  in  turn  creates  a dialog  box 
having  associated  dialog  box  procedures  GraphRsltContamDlgProc() , 
GraphRsltAirflowDlgProcO  and  GraphRsltExposDlgProcQ  located  in  the  files  GrphCtm.c, 
GrphFlow.c  and  GrphExp.c  respectively.  These  procedures  and  others  within  these  files  provide 
for  the  user  input  of  chart  options,  allocated  memory  for  data  to  be  plotted  and  creation  and 
display  of  the  windows  in  which  the  charts  are  displayed.  The  charts  are  created  and  displayed 
using  third  party  charting  software  know  as  Olectra  Chart.  Olectra  Chart  is  implemented  as  a 
DLL,  olch2d32.dll,  whose  import  library  olch2d32.lib  is  included  in  the  project  along  with  other 
related  header  files:  oc_color.h,  olch2d.h,  olch2dcm.h. 
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Appendix  3A 

This  appendix  displays  the  SketchPad  arrays  presented  in  section  3.4.1.  All  of  the  spreadsheets 
presented  in  this  appendix  refer  to  the  figure  below,  and  each  spreadsheet  represents  part  of  the 
arrays  in  which  SketchPad  data  is  stored.  The  associated  project  file,  SParrays.prj , is  installed  in 
the  samples  subdirectory  of  the  CONTAM  2.1  installation  directory. 


SketchPad  used  to  demonstrate  SketchPad  array  data. 
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